Referencje¶
Przewodniki referencyjne to techniczne opisy mechanizmów i sposobu ich obsługi. Materiał referencyjny jest zorientowany na informację.
Materiał referencyjny zawiera wiedzę propozycjonalną lub teoretyczną, do której użytkownik sięga w swojej pracy.
Jedynym celem przewodnika referencyjnego jest opisanie, w sposób jak najbardziej zwięzły i uporządkowany. Podczas gdy treść tutoriali i przewodników krok po kroku jest prowadzona przez potrzeby użytkownika, materiał referencyjny jest prowadzony przez produkt, który opisuje.
W przypadku oprogramowania, przewodniki referencyjne opisują samo oprogramowanie - API, klasy, funkcje itp. - i jak ich używać.
Twoi użytkownicy potrzebują materiału referencyjnego, ponieważ potrzebują prawdy i pewności - solidnych platform, na których mogą stać podczas pracy. Dobra dokumentacja techniczna jest niezbędna, aby dostarczyć użytkownikom pewności siebie w wykonywaniu ich pracy.
Referencja jako opis¶
Materiał referencyjny opisuje mechanizmy. Powinien być surowy. Trudno czyta się materiał referencyjny; konsultuje się go.
Nie powinno być żadnej wątpliwości lub niejednoznaczności w referencji; powinna być w pełni autorytatywna.
Materiał referencyjny jest jak mapa. Mapa mówi ci, co musisz wiedzieć o terytorium, bez konieczności wychodzenia i sprawdzania terytorium samodzielnie; przewodnik referencyjny pełni tę samą funkcję dla produktu i jego wewnętrznego mechanizmu.
Chociaż referencja nie powinna próbować pokazywać, jak wykonywać zadania, może i często musi zawierać opis tego, jak coś działa lub właściwy sposób użycia tego.
Niektóre materiały referencyjne (takie jak dokumentacja API) mogą być generowane automatycznie przez oprogramowanie, które opisują, co jest potężnym sposobem zapewnienia, że pozostaje ono wiernie dokładne w stosunku do kodu.
Kluczowe zasady¶
Opisywać i tylko opisywać¶
Neutralny opis jest kluczowym nakazem dokumentacji technicznej.
Niestety jedną z najtrudniejszych rzeczy do zrobienia jest opisanie czegoś neutralnie. To nie jest naturalny sposób komunikacji. Naturalne natomiast jest wyjaśnianie, instruowanie, dyskutowanie, wyrażanie opinii, a wszystkie te rzeczy stoją w sprzeczności z potrzebami dokumentacji technicznej, która zamiast tego wymaga dokładności, precyzji, kompletności i jasności.
Może być kuszące wprowadzenie instrukcji i wyjaśnień, po prostu dlatego, że opis może wydawać się zbyt niewystarczający, aby być użytecznym, i dlatego, że rzeczywiście potrzebujemy tych innych rzeczy. Zamiast tego, linkuj do przewodników krok po kroku, wyjaśnień i wprowadzających tutoriali.
Przyjmij standardowe wzorce¶
Materiał referencyjny jest użyteczny, gdy jest spójny. Standardowe wzorce to właśnie pozwalają nam efektywnie korzystać z materiału referencyjnego. Twoim zadaniem jest umieszczenie materiału, którego potrzebuje Twój użytkownik, tam, gdzie się go spodziewa, w formacie, który jest mu znany.
Jest wiele okazji podczas pisania, aby zachwycić czytelników swoim rozległym słownictwem i znajomością wielu stylów, ale materiał referencyjny zdecydowanie nie jest jednym z nich.
Szanuj strukturę mechanizmu¶
Sposób, w jaki mapa odpowiada terytorium, które reprezentuje, pomaga nam korzystać z pierwszej, aby znaleźć drogę przez drugie. Powinno być tak samo z dokumentacją: struktura dokumentacji powinna odzwierciedlać strukturę produktu, aby użytkownik mógł przechodzić przez nie jednocześnie.
Nie oznacza to wymuszania dokumentacji w nienaturalną strukturę. Ważne jest, aby logiczne, koncepcyjne uporządkowanie i relacje w kodzie pomagały nadać sens dokumentacji.
Dostarczaj przykłady¶
Przykłady są wartościowymi sposobami dostarczania ilustracji, która pomaga czytelnikom zrozumieć referencję, unikając ryzyka oddalenia się od zadania opisywania. Na przykład przykład użycia polecenia może być zwięzłym sposobem zilustrowania go i jego kontekstu, bez wpadania w pułapkę próby wyjaśnienia lub instruowania.
Język przewodników referencyjnych¶
- Domyślna konfiguracja logowania Django dziedziczy domyślne ustawienia Pythona. Jest dostępna jako
django.utils.log.DEFAULT_LOGGINGi zdefiniowana wdjango/utils/log.py Stwierdzaj fakty dotyczące mechanizmu i jego zachowania.
- Podkomendy to: a, b, c, d, e, f.
Wymieniaj komendy, opcje, operacje, funkcje, flagi, ograniczenia, komunikaty błędów itp.
- Musisz użyć a. Nie możesz stosować b, chyba że c. Nigdy nie używaj d.
Podawaj ostrzeżenia, gdy jest to właściwe.
Zastosowane do jedzenia i gotowania¶
Możesz sprawdzić informacje na opakowaniu żywności, aby pomóc sobie w podjęciu decyzji, co zrobić.
Kiedy szukasz informacji - istotnych faktów - nie chcesz być konfrontowany z opiniami, spekulacjami, instrukcjami lub interpretacją.
Oczekujesz również, że informacje będą przedstawione w standardowy sposób, abyś - gdy będziesz chciał wiedzieć o właściwościach odżywczych, sposobie przechowywania, składnikach, potencjalnych implikacjach zdrowotnych - mógł je szybko znaleźć i wiedzieć, że możesz na nich polegać.
Dlatego oczekujesz na przykład: Może zawierać śladowe ilości pszenicy. Lub: Waga netto: 1000g.
Z pewnością nie oczekujesz znaleźć na przykład przepisów lub twierdzeń marketingowych zmieszanych z tymi informacjami; to mogłoby być dosłownie niebezpieczne.
Sposób prezentacji materiału referencyjnego na produktach spożywczych jest tak ważny, że zazwyczaj jest regulowany prawem, i ten sam rodzaj powagi powinien mieć zastosowanie do całej dokumentacji referencyjnej.