4 ms·

How do you do documentation in terms of tools?

4 points by astree 9y ago

I want to replace our current documentation pipeline as it is to clumsy and complicated. We currently write documents in asciidoc. Then we do: asciidoc -[asciidoctor]-> docbook docbook -[custom xslt]-> custom latex custom latex -[xelatex]-> pdf Sadly this is quite fragile -especially the latex part - and I want to replace it with a more robust method. Some requirements are generation of header, footer and a cover sheet from meta data and a TOC from the headlines. It should also support the usual formatting stuff and source code highlighting. Ultimately the raw source should be version controllable. How do you do documentation? Do you have any suggestions that could fit my requirements?

billconan 9y ago
will doxygen work for you?
- astree 9y ago
  As we document much more than just sourcecode doxygen is not sufficient. The documents mostly consist of howtos, faqs and guides. --edit-- I mostly miss the styling options and the resulting pdfs don't look 'professional'
  - billconan 9y ago
    another thing you can try is https://pandoc.org/ https://pandoc.org/
    - astree 9y ago
      This is interesting :) Although it also seems to mostly use latex to generate pdf :/