Jestem twórcą rozwijającego się projektu open source. Obecnie zaczynam się denerwować, próbując znaleźć najlepszy sposób zarządzania dokumentacją. Oto opcje, które rozważałem:
- Witryna HTML
- Wiki Github
- Pliki Markdown hostowane na Github
- Umieszczanie wszystkich dokumentów w Github README.md
Dokumentacja jest już napisana w Markdown, po prostu nie mogę zrozumieć, jak chcę ją udostępnić. Bardzo lubię Git, ponieważ mogę rozgałęzić i oznaczyć dokumentację tak samo, jak rozgałęzić i oznaczyć źródło.
Mógłbym użyć biblioteki Markdown, aby przetłumaczyć Markdown na HTML i wyświetlić go na stylowej stronie internetowej. Będę musiał przesłać zmiany na stronę internetową w dowolnym momencie i trudno byłoby zarządzać wszystkimi różnymi „znacznikami” dokumentacji.
Github Wiki (o ile mi wiadomo) nie zmieniają się w zależności od gałęzi, w której się znajdujesz. Mogłem więc mieć tylko „główną” wersję dokumentacji w formularzu Github Wiki w danym momencie.
Umieszczenie tego w Github README jest całkiem fajne. Dostaję rozgałęzienia i tagowanie, ale jest to trochę męczące w użyciu i nie nadaje się do łatwej nawigacji.
Czy brakuje mi jakiegoś niesamowitego rozwiązania? Jakie inne opcje mam?
źródło
Odpowiedzi:
Powiedziałbym, że dokumentacja MUSI znajdować się w plikach kodu źródłowego (używając dowolnych znaczników), a następnie automatycznie generować dokumenty z nich.
Przynajmniej w swojej witrynie możesz generować sformatowane pliki do pobrania dokumentów jako część pakietu źródłowego, aby użytkownik nie potrzebował specjalnego narzędzia do dokumentów
Prawdopodobieństwo, że ktoś poprawi / doda funkcję, a następnie edytuje / doda trochę dokumentacji znaczników bezpośrednio przylegających do tego samego pliku, może być niskie, ALE szansa na znalezienie zupełnie innego pliku w innym repozytorium dokumentów, aby zrobić to samo, jest nieznaczna mniej niż zero.
Zawsze możesz mieć tutorial.h, który zawiera duże bloki tekstu, jeśli chcesz - ale traktuj go jako część źródła
źródło
Jeśli twój projekt jest biblioteką, nic nie przebije dokumentacji w stylu javadoc, aby udokumentować składnię API na podstawie komentarzy w samym kodzie.
Jeśli chodzi o dokumentację dotyczącą samouczków, przykładów użycia itp. Bardzo polecam korzystanie z formatu wiki. Inne projekty, które widziałem, mają osobne strony dla różnych gałęzi. Kiedy zakładasz nowy oddział, po prostu kopiujesz rzeczy, które nie zmieniły się na nowej stronie i stamtąd aktualizujesz.
Mój powód, by polecać wiki, jest niepotwierdzony, ale z własnego doświadczenia. Kilkakrotnie przyczyniłem się do aktualizacji dokumentacji do projektów typu open source, ale wszystkie były na wiki. Jeśli próbuję coś wymyślić, a dokumentacja wprowadza w błąd lub jest nieprzydatna, po tym, jak to wymyślę, zaktualizuję wiki, gdy będę w dokumentacji i będzie świeża w mojej głowie. Jeśli nie ze względu na poczucie oddania, przynajmniej dlatego, że wiem, że za rok lub dwa będę musiał ponownie to sprawdzić.
Jeśli nie ma wiki, bariera wejścia jest po prostu zbyt duża, aby przeszkadzać, między ustaleniem, w jaki sposób dokumentacja jest generowana, gdzie jest przechowywana, uzyskiwanie najnowszych informacji z kontroli źródła, jak wprowadzać zmiany, wprowadzać zmiany i poruszanie się po listach mailowych, aby zaakceptować łatkę.
Jeśli chcesz mieć ścisłą kontrolę nad dokumentacją, skorzystaj ze wszystkiego, co najbardziej ci odpowiada, ponieważ w większości będziesz jedynym, który ją aktualizuje. Jeśli chcesz zachęcić społeczność do udziału, skorzystaj z wiki.
źródło
Pliki Markdown hostowane ze źródłem działają bardzo dobrze.
Na przykład narzędzia docutils oparte na RST mogą na przykład tworzyć HTML lub LaTex (i pliki PDF) z jednego zestawu dokumentów.
To - w efekcie - łączy opcję 1 i opcję 3.
źródło
Jeśli nie masz nic przeciwko konwersji dokumentów z Markdown do reStructuredText, rozważ Sphinx . To jest tak proste jak obniżka, ale jest o wiele potężniejsze.
źródło