Język (tool) do tworzenia specyfikacji/dokumentacji technicznej

0

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.

0

Możesz skorzystać z jakiegoś systemu do zarządzania projektem np. JIRA, Redmine itp.
https://www.atlassian.com/software/jira/
http://www.redmine.org/

0

Chodzi o coś w stylu Cucumber?

0

doxygen generuje z odpowiednio sformatowanych komentarzy w kodzie dokumentacje

1

Dzięki wszystkim za odpowiedzi.

@Madaoo: nie, nie chodziło mi o zarządzanie projektem.
@krwq: znam doxygen, ale jednak rzadko używam, tylko w interfejsach w zasadzie
@winerfresh: poczytałem o tym cucumber i to właśnie czegoś takiego szukam. Behavior Driven Development, poczytam o tym, zobaczę na ile mogę istniejące rozwiązania zastosować.

Jeszcze raz dzięki za odpowiedzi

0

@rafal__: Będąc precyzyjnym to chodzi o Gherkin (to jest język, którego używa Cucumber). Możesz poszukać gotowego rozwiązania dla twojego języka lub napisać własną implementację, nie należy to do zbyt skomplikowanych rzeczy.

1 użytkowników online, w tym zalogowanych: 0, gości: 1, botów: 0