Jak zorganizować dokumentację? Skorzystać z drzewka hierarchii czy stosować cross-linki?

Deweloperzy nie lubią pisać dokumentacji

Istnieje coś co łączy większość programistów - nienawidzą pisać i utrzymywać dokumentacji. Wiele firm ma po prostu kiepską dokumentację: nie istniejącą, źle zorganizowaną, nieaktualną lub po prostu fatalnie napisaną. Nieuporządkowane długie wiadomości na Slacku lub e-maile, a nawet dokumenty Worda sporządzane ad-hoc w celu wyjaśnienia koncepcji lub projektów to nie dokumentacja.

Co ciekawe, gdy pojawia się jakiś menedżer, który próbuje zmusić wszystkich do używania „odpowiednich” narzędzi do dokumentacji, dokumentacja czasami się jeszcze pogarsza. Nieuchronnie jedyna „właściwa” dokumentacja po prostu się rozpada i ostatecznie nikt jej nie używa jeśli nie ma do niej przekonania.

Ilość czasu i wysiłku poświęconego na dokumentację sporządzaną ad-hoc najlepiej pokazuje, że to nie jest ulubione zajęcia dewów. Nawet jeśli wszyscy wiemy, że oszczędza to czas i wysiłek oraz pomaga zwiększyć autonomię naszych współpracowników. W końcu niestaranna dokumentacja to jeden z 7 grzechów głównych dewelopera.

Problem wcale nie musi polegać na tym, że narzędzia dokumentacyjne, na których tyle firm ustandaryzowało się, są błędne, powolne czy też prezentują sobą katastroficzny UX. Często główna przyczyna niepowodzenia w prowadzeniu dokumentacji to sposób w jaki te narzędzia próbują porządkować informacje.

Drzewko hierarchii

Oczywistym sposobem organizacji informacji jest użycie drzewa. Za przykład niech posłuży sposób działania systemów plików. Mamy hierarchię plików i wszystko jest zorganizowane w tym systemie. Aby znaleźć jakąś informację X, możemy po prostu zacząć od góry i podróżować w dół, wybierając gałąź, która jest najbardziej sensowna dla tego, czego szukamy.

Takie zrównoważone drzewo ma czas wyszukiwania O (log (n)). Wydaje się to świetne: zawsze powinniśmy być w stanie znaleźć to, czego szukamy, w krótkim czasie. Ale sprawy komplikują się gdy na przykład mamy wiedzę, którą chcemy udokumentować, a która dotyczy zarówno Projektu A, jak i Projektu B - gdzie ona idzie w tej hierarchii? Czy powielamy informacje w obu sekcjach? Czy tworzymy nową sekcję? Czy po prostu umieścimy tą wiedzą w Projekcie A i w jakiś sposób łączymy odnosimy się do niej gdzieś w dokumentacji Projektu B? A może po prostu umieściliśmy go w Projekcie A, ponieważ jest nieco bardziej odpowiedni i po prostu ignorujemy Projekt B? Tak czy siak – nie będzie dobrze, nasze informacje mają duże szanse być źle zorganizowane i nie podejmiemy właściwej decyzji bo nie mamy na to szansy.

Wiki czyli cross-linki

Wikipedia i Arch Linux Wiki cieszą się uznaniem jeśli chodzi o zarządzanie informacjami i zbiorową wiedzą – i nie bez powodu. Dzieje się tak m.in. dlatego, że informacje są zorganizowane w inny sposób niż w przypadku drzewka hierarchii.

Zamiast hierarchii, w której wszystko jest zorganizowane, każdy dokument jest zasadniczo swobodnie usytuowany. Zamiast określać, z jakimi innymi dokumentami jest powiązany dokument, używa się łączy (linków) między dokumentami, aby utworzyć relację między nimi. Spójrz na przypadkową stronę Wikipedii i zobacz, ile jest linków do innych powiązanych stron. Ta gęsta sieć utworzona przez linki między stronami sprawia, że tak prowadzony system dokumentacji jest bardziej przyjazny dla człowieka.

Sprawdź oferty pracy na TeamQuest

Rozważmy czas wyszukiwania dowolnej informacji. Jest to nieco trudniejsze do ustalenia, ponieważ zależy od gęstości linków. Jeśli trafimy na niewłaściwą stronę, zamiast potencjalnie wracać do katalogu głównego, możemy po prostu zrobić losowy spacer po stronie, na której się znajdujemy. W nawet minimalnie zorganizowanym systemie powinno to nadal prowadzić nas do informacji, których potrzebujemy, ponieważ strony będą zawierać linki do innych odpowiednich stron i finalnie znajdziemy to czego szukamy.

Co ważniejsze, można po prostu dodać nowe informacje i nie trzeba podejmować decyzji, gdzie umieścić te informacje. Jeśli jakaś informacja dotyczy Projektu A i Projektu B, po prostu dodajemy ją jako nowy dokument i łączymy z Projektem A i Projektem B.

Co lepsze?

Oczywiście nie oznacza to, że nie powinieneś stosować w ogóle drzewka hierarchii. System oparty na cross-linkach nie rozwiązuje wszystkich problemów. Bałagan zawsze będzie bałaganem, niezależnie od tego, czy jest w hierarchii, czy też linkowany do innego bałaganu. Ale na pewno dokumentacja oparta na hierarchii jest mniej skalowalna i wymaga znacznie więcej wysiłku i samodyscypliny w jej prowadzeniu.