Grupa docelowa
Myślę, że odpowiadając na to pytanie, naprawdę musisz zapytać, kto powinien przeczytać tę dokumentację. Deweloper ma rażąco inne potrzeby niż użytkownik, a nawet analityk biznesowy.
- Jako programista: dokumentacja związana z badanym kodem, szczegóły takie jak umowa interfejsu i przykłady użycia. Być może trochę dokumentacji wysokiego poziomu i specyfikacji protokołu dla dobrego pomiaru.
- Jako użytkownik: dokumentacja dostępna za pośrednictwem menu pomocy lub dostępnej strony internetowej na temat korzystania z oprogramowania.
- Jako analityk biznesowy: przydatna jest dokumentacja dostępna w postaci dokumentów lub dostępna strona internetowa. Najlepsza jest niewielka ilość szczegółów na temat protokołów, architektury wysokiego poziomu i przypadków użycia.
Konserwacja
To, gdzie umieścić źródło tej dokumentacji, będzie zależeć od odbiorców i tego, kto pisze dla odbiorców.
- Masz tylko dom programistów? Umieść wszystko w kodzie. Zachęci to do aktualizacji. Będziesz musiał pracować nad kulturą, która zachęca do aktualizacji dokumentacji, aby była tak ważna jak zmiany w kodzie.
- Masz dom programistów i autorów dokumentacji? Podziel obowiązki. Używaj narzędzi programistycznych dla programistów, używaj narzędzi twórców dokumentacji dla twórców dokumentacji.
Tam, gdzie to możliwe, upewnij się, że przykłady kodu lub przypadki użycia mogą być wykonane. Automatyzuj ich wykonywanie i wewnętrznie oznaczaj awarie. Możliwe, że te strony są słabej lub złej dokumentacji.
Dodatkowo, niezależnie od narzędzi, w których zdecydujesz się napisać dokumentację, potrzebujesz niezawodnych środków do powiązania określonej wersji dokumentacji z określoną wersją kodu. Jest to nadal korzystne nawet w szczęśliwych chmurach dzięki jednemu wiecznie zielonemu wdrożeniu.
Dokumentacja integrująca
Integracja może być potrzebna do sporządzenia dokumentacji, ale należy pamiętać, że tylko użytkownik oczekuje, że jedno miejsce uzyska dostęp do całej potrzebnej dokumentacji.
Analityk biznesowy jest bardzo zadowolony ze specyfikacji API, specyfikacji projektów i scenariuszy użycia, które można znaleźć w osobnych dokumentach lub osobnych sekcjach witryny.
Deweloper woli wszystko, co widać ze źródła, ale bardzo cieszy się z posiadania kilku dokumentów projektowych wysokiego poziomu i szczegółowych dokumentów specyfikacji protokołu poza kodem, choć najlepiej w ramach tej samej kasy.
Twój przypadek
Szczerze mówiąc, dokumentacja na twojej wiki prawdopodobnie nie jest tego samego rodzaju dokumentacją w twojej bazie kodu. Scalenie też może nie mieć sensu.
Z drugiej strony integrację tych dwóch można uzyskać na kilka prostych sposobów.
- Narzędzia dokumentacji źródłowej (takie jak doxygen) mogą generować HTML, a wiki żyje na serwerze WWW. Byłoby prostym punktem integracji, aby po prostu podać wersję wbudowaną obok wiki i połączyć je ze sobą.
- Niektóre produkty wiki pozwalają na uruchomienie wiki bezpośrednio z pliku, który można zameldować w bazie kodu. Daje to proste narzędzie wysiwyg przy zachowaniu powiązania dokumentacji z kodem.
- Można także dostosować inne formaty, takie jak pdf, ale sprowadza się to do konkretnego narzędzia, którego chcesz użyć. Sensowne może być zeskrobanie wiki do plików przecen i przekazanie go za pomocą doxygen (lub innych narzędzi). Sensowne może być osobne utworzenie strony wiki i źródła oraz użycie narzędzia do łączenia plików pdf.
Na koniec dowiedz się, który system dokumentacji ma niskie koszty utrzymania, i pomaga w dostarczaniu produktu wysokiej jakości, co widać na widowni programistów, analityków biznesowych i użytkowników. Wszystko, co przeszkadza którejkolwiek z tych grup, koniecznie obniży jakość produktów.