Gdzie umieścić dokumentację kodu?

Obecnie używam dwóch systemów do pisania dokumentacji kodu (używam C ++):

• Dokumentacja o metodach i członkach klasy jest dodawana obok kodu, w formacie Doxygen. Na serwerze Doxygen jest uruchamiany na źródłach, dzięki czemu dane wyjściowe można zobaczyć w przeglądarce internetowej
• Strony przeglądowe (opisujące zestaw klas, strukturę aplikacji, przykładowy kod, ...) są dodawane do Wiki

Osobiście uważam, że takie podejście jest łatwe, ponieważ dokumentacja członków i klas jest bardzo zbliżona do kodu, podczas gdy strony przeglądowe są naprawdę łatwe do edycji na Wiki (a także łatwe dodawanie obrazów, tabel, ...). Przeglądarka internetowa pozwala zobaczyć obie dokumentacje.

Mój współpracownik sugeruje teraz, aby umieścić wszystko w Doxygen, ponieważ możemy następnie utworzyć jeden duży plik pomocy ze wszystkim w nim (używając albo HTML WorkShop Microsoftu, albo Qt Assistant). Obawiam się, że edytowanie dokumentacji w stylu Doxygen jest znacznie trudniejsze (w porównaniu z Wiki), szczególnie gdy chcesz dodać tabele, obrazy, ... (lub czy istnieje narzędzie do podglądu Doxygen, które nie wymaga generowania kod, zanim zobaczysz wynik?)

Czego używają duże projekty open-source (lub zamknięte) do pisania dokumentacji? Czy dzielą to również na styl Doxygen i Wiki? Czy używają innego systemu?

Jaki jest najbardziej odpowiedni sposób na ujawnienie dokumentacji? Za pośrednictwem serwera / przeglądarki internetowej lub dużego (kilka 100 MB) pliku pomocy?

Jakie podejście przyjmujecie podczas pisania dokumentacji kodu?

Posiadanie całej dokumentacji w jednym systemie zamiast dwóch może być prawdziwą zaletą. Funkcje takie jak tworzenie kopii zapasowych i przywracanie, wersjonowanie, globalne wyszukiwanie, globalne wyszukiwanie i zamiana, łączenie oraz, jak napisałeś, umieszczenie wszystkich dokumentów w jednym dokumencie końcowym, zazwyczaj będzie działać z mniejszym „tarciem”, gdy nie musisz utrzymywać dwóch różnych systemy z nakładającymi się możliwościami.

Z drugiej strony musisz zastanowić się, czy te zalety przewyższają łatwość korzystania z Wiki. Krąg edycji / generowania / udoskonalania edycji / generowania ponownie może być szybszy z twoją Wiki. Wydaje mi się, że można uzyskać ten cykl dość szybko dzięki doxygen, zachowując strony przeglądowe jako osobny podprojekt doxygen. Możesz skorzystać z zewnętrznych możliwości łączenia doxygen, co oczywiście nie zastępuje „szybkiego podglądu”, ale krok w tym kierunku. Do tej pory nie zrobiłem tego sam, ale sądzę, że musisz sam to wypróbować, jeśli chcesz wiedzieć, czy to działa w twoim przypadku.

Odnośnie innych projektów: Myślę, że narzędzie takie jak doxygen służy przede wszystkim do dokumentacji bibliotek. Jeśli nie jesteś zewnętrznym dostawcą bibliotek i wszyscy korzystający z twoich bibliotek mają pełny dostęp do kodu źródłowego, to potrzeba takiego narzędzia jak doxygen jest wątpliwa. Na przykład w naszym zespole nie mamy prawie żadnych zewnętrznych dokumentów poza kodem, z wyjątkiem dokumentów użytkowników końcowych i dokumentów naszych modeli baz danych. Naszymi podstawowymi narzędziami do tego rodzaju dokumentacji są docbook i fop , co daje nam satysfakcjonujące wyniki.

Najpierw użyj dokumentacji kodu. Dodaj Wiki i inne metody, jeśli to możliwe

Wiem, to będzie trudne do utrzymania.

Praktyczna odpowiedź:

W praktyce pierwszą rzeczą, którą robią programiści, jest sprawdzenie kodu.

Jako programista lubię mieć zewnętrzną dokumentację, taką jak Wiki, podręczniki. Ale pierwszą rzeczą, którą robię, jest przejrzenie kodu (czasem od innych programistów, czasem moich).

Jako programista, który pracował w kilku projektach i klientach, robię, co tylko możliwe, aby dodać zewnętrzną dokumentację, ale często mam dużo pracy i nie byłem w stanie obsługiwać wiki.

Czasami kierownicy projektów i inni szefowie nie dbają o dokumentację, a czasem inni programiści nie.

A najlepsze, co mogę zrobić, to dodać kilka komentarzy do kodu.

Powodzenia

Niektóre używają innych systemów - na przykład Sphinx Pythona , mają one system doc all-in-one, który buduje wszystko (działa również w C / C ++)

Zawsze myślę, że dokumentacja jest oddzielna od kodu, doxygen jest świetny, ale służy do przeglądu interfejsu API, a nie do „dokumentacji”. Do tego wiki jest świetna, ale wolę używać ASCIIDOC i przechowywać wyniki tego w kontroli źródła wraz z kodem, głównie dlatego, że mogę generować z niego pliki PDF, aby przekazać je innym osobom (np. Testerom, klientom itp.)

Doxygen umożliwia tworzenie plików PDF, HTML, stron wiki, prawie wszystkiego, co tylko możesz wymyślić.

Osobiście wolę mieć Doxygen i wiki oraz skrypt lub coś do sprawdzenia, kiedy się rozejdą.

Od wersji 1.8.0 doxygen obsługuje Markdown , co powinno ułatwić pisanie stron statycznych podobnie jak w systemie Wiki.

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.

Jeśli używasz ASCII, powinieneś przechowywać swoją ukrytą dokumentację w wysokiej części kodu źródłowego! Wtedy tylko najbardziej sprytni (czytaj: zasłużyli) użytkownicy mają możliwość korzystania z twoich dokumentów.

Prawdziwą zaletą może być posiadanie dokumentacji w dobrze zdefiniowanym, łatwo eksportowalnym, przenośnym formacie. Jeśli sfinks umrze (mało prawdopodobne), po prostu przekonwertuję na inny system, co, jak sądzę, byłoby zadaniem skryptowalnym. Przenoszenie danych poza wiki (prawdopodobnie przechowywane w bazie danych w zastrzeżonym formacie może być uciążliwe).