---
# System prepended metadata

title: Luźne przemyślenia dt. dokumentacji projektu Mimiker
tags: [mimiker]

---

# 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



