Geek Answers Handbook

Good markup for writing technical documentation

What would you recommend as a good markup language for writing technical design documentation? Ideally, I would like to have at least the following:

  • It works well in version control - I would like to be able to store the documentation in the repository with the source that it is developing.
  • The ability to make UML-ey diagrams and other relevant methods in markup - the ability to create class diagrams, code snippets, etc. The documentation will be helpful.
  • The ability to easily create well-laid out documents from markup - so that they can be created as part of the site assembly along with API documentation, for example.

AsciiDoc is suitable for numbers 1 and 3. Docbook and TeX. I have not yet studied how well they fit, but I was wondering if there was anything else worth investigating ...

EDIT: for technical documentation, I refer to documents that are primarily related to developers, and almost certainly do not apply to clients, but will potentially be reviewed by team leaders, etc ...

+5
source share
4 answers

Sphinx . Sphinx reStructuredText . Python, , (, API), , .

" " " ". Sphinx , () , .

" UML-ey " Sphinx, Graphviz, . Python, , , , .

+4

, -, - Wiki .

+1

Graphviz AsciiDoc, . 2.

+1

Docbook ( ): ( XML-), ( XSLT docbook). , , (, HTML- Windows). Docbook , . , AsciiDoc Docbook, .

My experience with AsciiDoc (although I didn’t use it, I just saw what two people are doing with it) is that although it’s quite powerful, you don’t have any significant help writing (i.e. there is no Intellisense,) , and it was quite difficult to extract a really well-formed PDF file from it. But now it works, and in the future it will be easier.

+1
source

More articles:


All Articles