Wprowadzenie

Istnieją różne sposoby dostępu do informacji:

  1. (chrono)logiczny, jak czytanie strona po stronie, wiersz po wierszu, aż dotrzesz do końca publikacji,
  2. tematyczny, jak przejście do spisu treści i skok wprost do części, która Cię interesuje, pod warunkiem, że treść jest podzielona na sensowne jednostki treści,
  3. poprzeczny, jak podążanie za sekcją „powiązane wpisy" opartą na podobieństwie treści (definiowanym ręcznie, za pomocą tagów i słów kluczowych, lub wyuczonym przez analizę tematyczną AI), lub za jawnymi odsyłaczami. Na przykład większość witryn ma archiwa wymieniające wszystkie strony mające określony tag/słowo kluczowe, książki mają glosariusze.
  4. oparty na podpowiedziach, jak przedstawienie bibliografii bardziej pogłębionych publikacji lub sekcji „więcej informacji" na końcu treści, albo antycypowanie późniejszej treści,
  5. oparty na źródłach, podążanie za odsyłaczami (zwykle przypisami dolnymi lub bocznymi) do publikacji, z których wydobyto informację, głównie w celach weryfikacyjnych,
  6. wyszukiwanie informacji, czyli wyszukiwarka.

Musisz wspierać je wszystkie naraz, ponieważ są komplementarne, a najlepszy w danym kontekście zależy od początkowej wiedzy i potrzeb czytelnika. Żaden z tych sposobów nie jest lepszy od pozostałych. Oznacza to, że trzeba dokonać sporego „upychania słów kluczowych" w swoim tekście, aby zapewnić, że oparta na słowach kluczowych analiza treści oraz wyszukiwanie informacji według słów kluczowych będą działać zgodnie z oczekiwaniami.

Podręcznik/dokumentacja to nie kurs, ale trzymanie się suchej listy funkcji/elementów sterujących GUI i ich definicji jest… zbyt suche. Musisz tworzyć powiązania między treściami (co nie sprowadza się jedynie do linków HTML). W Ansel przepływy pracy zaczynają się od celu i rozwijają narzędzia potrzebne do jego osiągnięcia. Dokumentacja zaczyna się od narzędzi i przedstawia, jak i gdzie mogą one być użyte. Ale to są dwa końce spektrum, a rzeczywistość zawsze leży gdzieś pośrodku.

Wiedza i tak jest grafem sieciowym . Musisz tylko zadbać o powiązania między węzłami. Są one co najmniej tak samo ważne jak treść.

Praktyczna implementacja w Ansel

Ansel używa Hugo  jako swojego CMS, zarówno do dokumentacji, jak i do reszty witryny. Praktyczna implementacja zasad sformułowanych powyżej będzie musiała uwzględnić podstawowe funkcje Hugo.

Dostęp (chrono)logiczny i tematyczny

Treść w Hugo jest zorganizowana w sekcje , które są zasadniczo podfolderami głównego folderu /content. Podfoldery mogą być zagnieżdżane w nieskończoność. Motyw witryny przedstawia widok drzewa wszystkich sekcji w lewym pasku bocznym, na szerokich ekranach (komputery stacjonarne). Najwyższe poziomy sekcji i podsekcji można zwijać/rozwijać na żądanie użytkownika. Ten widok drzewa zapewnia najwyższego poziomu spis treści, który działa jako dostęp tematyczny.

Wewnątrz sekcji względną kolejność stron można zdefiniować ręcznie za pomocą parametru weight  w nagłówkach Markdown, w następujący sposób:

1---
2title: Documenting Ansel
3date: 2025-10-13
4weight: 9
5---
6
7My content here

Parametr weight jest opcjonalny. Jeśli nie jest użyty, listy stron będą zwykle porządkować treść według date, ale mogłyby też stosować kolejność alfabetyczną według tytułu strony. Ta kolejność zapewnia dostęp (chrono)logiczny.

Wewnątrz stron, jeśli w treści są więcej niż dwie sekcje (definiowane przez tytuły drugiego poziomu, np. <h2> w HTML lub ## w Markdown), Hugo automatycznie doda wewnętrzny spis treści do prawego paska bocznego, na szerokich ekranach (komputery stacjonarne).

Dostęp poprzeczny

Tagi można zdefiniować w witrynie za pomocą parametru tags w nagłówku Markdown, w następujący sposób:

1---
2title: This page title
3date: 2022-12-04
4tags:
5    - color science
6    - pipeline
7---
8
9Your content

Tagi są opcjonalne i są wyświetlane jako klikalne linki w kilku miejscach motywu witryny. Kliknięcie jednego tagu otwiera jego archiwum, wymieniające wszystkie strony mające ten tag. To zapewnia dostęp poprzeczny.

Autorów zachęca się również do dodawania odsyłaczy w swojej treści, ze stron witryny do innych stron witryny, aby wspierać dostęp poprzeczny. Pojęcia, które mają swój wpis w witrynie, powinny być zamieniane w linki do strony opisującej każde pojęcie.

Oparty na podpowiedziach

Autorzy mogą swobodnie dodawać sekcję Bibliografia lub Więcej informacji na końcu swoich stron, z listą publikacji i linków. Publikacje te mogą być wewnętrzne lub zewnętrzne względem projektu Ansel. Mogą być peryferyjne wobec tematu poruszanego w treści.

Możliwe jest również zakończenie stron otwarciem na następny logiczny krok, gdy pisze się o przepływach pracy lub modułach.

Oparty na źródłach

Hugo wspiera rozszerzony Markdown, który wspiera przypisy dolne . Zaleca się je do odsyłania do źródeł, w następujący sposób:

1The typical observer has Just Noticeable Difference (Delta E) of 2.3[^1]
2
3[^1]: Some Author, Some Publisher, _A real-world, large-sampled, study of vision parameters for white, rich, educated, American students of the Rochester Institute of Technology_, (some year). [URL](https://doi.org/xxxxx)

Ansel nie zdecydował się na ten moment na żaden konkretny akademicki format cytowania źródeł, choć styl cytowania IEEE  wydaje się najlepiej dopasowany do podejścia z przypisami dolnymi o indeksie numerycznym.

Zadbaj o dołączenie DOI  publikacji lub przynajmniej jakiegoś długoterminowego adresu URL, pod którym można ją uzyskać teraz i w przyszłości.

Wyszukiwanie informacji

Na razie tą częścią zajmuje się Chantal . Indeks sieciowy jest aktualizowany ręcznie i okresowo.

Wytyczne

Pisanie, nawet techniczne, to sztuka, którą trudno sprowadzić do zestawu ściśle określonych wytycznych lub najlepszych praktyk, ponieważ zależy to od kontekstu. Powinieneś uważać, aby nie być bardziej papieskim niż sam papież. Dobrą regułą praktyczną jest pisanie w celu rozwiązywania problemów, co oznacza, że zacznij od zadania sobie pytania, dlaczego i skąd czytelnik trafił na stronę, którą piszesz:

  1. jaki rodzaj wiedzy czytelnik ma rzekomo/zakładanie już posiadać?
    • czytelnik powinien idealnie być świadomy tych wymagań wstępnych, więc może zacznij od listy linków,
    • wszystko, czego nie ma na tej liście, powinno być zdefiniowane i wyjaśnione na Twojej stronie,
  2. jaki rodzaj zadania czytelnik próbuje wykonać, co doprowadziło go do tej strony?
    • czy chce szybkiej ściągi, czy szczegółowej instrukcji, czy teoretycznego tła? Być może będziesz musiał wybrać jeden arbitralnie.
    • to zadecyduje, jakie podpowiedzi możesz dodać w tekście, aby ulepszyć sieć wiedzy,
    • to prawdopodobnie powinno ukierunkować cały punkt widzenia Twojej treści oraz jej długość/głębię.

Dobrym sposobem oceny jakości dokumentacji jest przyjrzenie się często zadawanym pytaniom (lub najsłabiej rozumianym tematom) na forach. Jeśli temat jest już omówiony, ale pytania wciąż się pojawiają, może to być spowodowane tym, że dokumentacja nie jest jasna lub odpowiednie strony są pogrzebane w sieci i niewystarczająco odkrywalne.

Translated from English by : Claude. In case of conflict, inconsistency or error, the English version shall prevail.