Piszę sobie wieczorami mały projekt. Zacząłem pisać dokumentację, a raczej luźne zapiski, żeby móc przypomnieć sobie za parę miesięcy jakie idee przyświecały poszczególnym kawałkom kodu. Zapisuję to po prostu w pliku txt, diagramy w formacie graphviz (dot). Jednak myślę o "ulepszeniu" procesu spisywania wymagań, specyfikacji, szukałem czegoś takiego jak język specyfikacji.
Może używacie w pracy lub hobbystycznie języka/narzędzia do tworzenia dokumentacji?
Czego oczekuję po takim języku/narzędziu:
- łatwość utrzymywania w repozytorium kodu (format tekstowy, nie binarny; jeśli używa się graficznego narzędzia w celu edycji, to chciałbym, aby pojedyncza zmiana była również pojedynczą zmianą w pliku, by zmiany można było śledzić zwykłym diffem)
- łatwość konwersji do innych formatów
- czytelność kodu
- opcjonalnie: możliwość tworzenia diagramów UML, które będzie można przekonwertować do postaci graficznej
- opcjonalnie: możliwość tworzenia szkieletów kodu testów na podstawie warunków zawartych w specyfikacji
Myślałem, by po prostu zapisywać dokumentację w pliku XML o ustalonych przeze mnie tagach, a następnie konwertować to do innych formatów za pomocą XSLT (ew. pythonowych skryptów), tak działa na przykład DocBook.