Przypomnieć sobie Przywołać
Przywołać informacje, których nie dało się zapamiętać — od parametrów po kody błędów.
Jedną z rzeczy, które utrzymują wartość dokumentacji po wielu latach użytkowania, jest jej rola jako materiału referencyjnego. Przeglądamy strony podręczników, aby przypomnieć sobie, odszukać lub wydobyć informacje, których nie udało się zapamiętać — od parametrów i kodów błędów po dopuszczalne wartości.
Przykłady dokumentacji pomagającej sobie przypomnieć to dokumentacja referencyjna Dockerfile oraz dokumentacja składni YAML w GitLab CI/CD. Przedstawiają łatwe do przeszukiwania, dobrze uporządkowane informacje o szczegółach, które użytkownik musi przywołać, aby wykonać kolejne techniczne „zaklęcia”.
Dokumentacja referencyjna jest fundamentem długotrwałej użyteczności produktu. Materiały tworzone z myślą o innych działaniach można przeczytać raz i przyswoić, natomiast dokumentacja referencyjna pozostaje stale cenna, gdy użytkownicy pogłębiają wiedzę i podejmują coraz bardziej złożone wdrożenia.
Co użytkownik chce zrobić
Dokumentacja referencyjna zachowuje wartość po wielu latach. Użytkownicy przeglądają podręczniki, aby przypomnieć sobie, odszukać lub wydobyć informacje, których nie zdołali zapamiętać.
Sygnały, że dokumentacja tego nie zapewnia
- Użytkownicy szukają parametru lub kodu błędu i niczego nie znajdują.
- Materiały referencyjne są rozproszone po wpisach na blogach i zapisach rozmów.
- Brakuje przeszukiwalnej, uporządkowanej dokumentacji składni lub ustawień produktu.
Dwa przykłady z praktyki
Typowe rodzaje treści
| DITA | Diátaxis | Good Docs Project |
|---|---|---|
| <reference>, <refsyn>, <properties> | Dokumentacja referencyjna | Dokumentacja referencyjna, Słownik |
Jedna metryka
trafność wyszukiwania w dokumentacji referencyjnej · Odsetek wyszukiwań referencyjnych, które prowadzą do właściwej strony.