# Luźne przemyślenia dt. dokumentacji projektu Mimiker ###### tags: `mimiker` # Idee - trzymać dokumentację najbliżej miejsca jej użycia - proste narzędzia - pisanie dokumentacji ma być naturalne - jak najmniej barier - mamy mało czasu na utrzymywanie dokumentacji - maksimum treści, minimum formy # Pytania - gdzie i jaką dokumentację utrzymywać, np.: * procedury interfejsu: argumenty i jej zadanie w pliku nagłówkowych * procedury które uważamy z API to w średniopoziomowej # Rodzaje dokumentacji: - dokumentacja podsystemów - dokumentacja uruchomieniowa - w kodzie ## Dokumentacja podsystemów - kluczowe pojęcia - jakie zadania pełni podsystem? - jakie są kluczowe struktury danych i algorytmy? Struktura podobna do manpage'ów, ale bardziej rozbudowana. Zawiera zarówno opis wysokopoziomowy (high level overwiew) jak i opis kluczowych funkcji oferowanych przez moduł. W treści dokumentacji odnośniki do kodu (OpenGrok) z jednej strony, do teorii z drugiej. Sposób prezentacji tego rodzaju dokumentacji jest drugorzędny. Może być to albo wiki w githubie, albo katalog z plikami md/html albo jeden wielki pdf, albo też dokument [readdoc](https://readthedocs.org/). Link na stronie [Mimikera](https://mimiker.ii.uni.wroc.pl/). ### Najwyższy poziom (plik home) [intro.9](https://man.netbsd.org/intro.9) wyglądałoby ok, gdyby przy każdym podsystemie pojawiła się strona: - zadania podsystemu (tj. motywacja) - historyjka spinająca jego komponenty (**klej** między komponentami) ### Średni poziom Opisuje dokładniej zadania podsystemu, kluczowe algorytmy i struktury danych oraz na sam koniec tą część interfejsu, którą uważamy za stabilną. Może tutaj coś na temat polityki zarządzania zasobami i blokadami w tym podsystemie? [pmap.9](https://man.netbsd.org/pmap.9) Komentarz do funkcji wydaje się, że powinien być w pliku nagłówkowym. Zadanie funkcji skrótowo można podać. Musi być odnośnik do pliku nagłówkowego. Jak się tego używa? Jakie są interakcje z innymi podsystemami? ## Dokumentacja wdrożeniowa Dotyczy: - konwencji kodowania - konwencji tagów i dokumentowania kodu - konwencji testowania, pisania i uruchamiania testów - sposobu kontrybucji do projektu - struktura katalogów - build system - toolchain - test framework - itp. Tą dokumentację będziemy trzymać bezpośrednio w repozytorium, w postaci plików Markdown. Główny plik w katalogu `/docs`. ## Dokumentacja w kodzie To trzeba utworzyć na podstawie bieżącego kodu. Wybrać najlepiej udokumentowane pliki i na podstawie tego skompilować konwencję. Tu powinny pojawiać się odnośniki do źródeł, które uznajemy za wzorcowe, żeby rozstrzygać wątpliwości przez przykład. # Linki https://guides.lib.berkeley.edu/how-to-write-good-documentation https://google.github.io/styleguide/ https://jacobian.org/series/great-documentation/ https://www.linuxfoundation.org/en/resources/open-source-guides/using-open-source-code/ https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project https://en.wikipedia.org/wiki/Software_documentation https://tallyfy.com/software-documentation-tools https://helpjuice.com/blog/software-documentation