   Writing documentation without focusing on markup
  Alright, so right now I'm in this heated discussion with a colleague about writing documentation for our software.In it's current state the documentation is a freaking mess. It mostly consists of Word documents and are usually half completed and completing them usually turns into a mess because you need to reference other documents. Everyone is sick of it, so we're looking for a new way to document things. I immediately suggested to go with LaTeX: it's a great way to document things, and depending on what we want, it's very easy to generate the output, for instance PDF documents, or HTML pages. However, my colleague actually wants to write the documentation in HTML, because he thinks it's great for displaying documentation. While I agree it's great to display it, it's far from usable to write it. I also opted to use DocBook or use a wiki, but he insists on HTML because everyone knows it. Frankly, that's a bullshit reason. Documentation should be completely free of markup for that matter, or as much as possible. LaTeX does exactly this, but apparantly he thinks it sucks because he saw an example of it on wikipedia.My question: what tools are out there to make writing documentation not a hell?Toolmaker   
  LaTeX contains about as much markup as Strict XHTML, the only fundamental difference is that LaTeX allows the definition of commands, but then this becomes a mix of content and format. I use and suggest XML + XSLT. Everyone who knows XHTML and who isn't brain-dead can also write XML, and immediately view the result, transformed by an XSL stylesheet, in a web browser, which is something that LaTeX cannot do without a multi-pass compiling process that's not quite obvious to the neophyte. You also get the added benefit that it's easier to write inline code examples in XML+XSLT than it is in LaTeX.   ;  And if you're using Microsoft compilers, you can even create your API documentation in the same way.Their C++ compiler has a switch that extract XML comment blocks from the source during a compile and writes them into a separate XML file that can then be displayed with an XSLT or even be transformed into a help file using Microsoft's "Sandcastle" tool.   ;  Couldn't you merge the documentation with the code itself and generate the documentation automatically with a tool?EDIT: Too slow...   ;  I have been assessing the formats for my documents recently and i came to the conclusion that the final format should be HTML, which primarily comes from source annotations and can be added to.Even the Design and Tech documents are to be finalised in HTML but also converted to pdf for easy packing and cross platform readability.Id really like to see IDEs auto-hide documentation text completely, with added features for then adding notes and displaying documentation when its needed.   ;  Use a documentation-generator tool to parse your code for specially formatted comments.  this is your API reference.For high level concepts, DocuWiki is perfect.  Try markdown as a "natural formatting syntax" - it renders to HTML but doesn't get in the way of human parsing.  StackOverflow uses it.   ;  Project documentation format should be strictly controlled. The more controlled it is, the less time people will spend on formatting. I actually find HTML to be very adept at formatting official project documentation. It's very easy to build a very simple style sheet that generates roughly the same look-and-feel across all browsers.However, you don't want it *stored in* HTML. XML + XSLT as suggested previously is overkill, I believe. It provides too much flexibility to the document writer. As I said before, formatting options get in the way of writing documentation. I personally like implementing Markdown-like solutions for this problem. I don't bother with strict adherence to Markdown -- it's not so difficult to figure out that standardization is a big deal. I find that supporting bulleted lists (primarily numbered), links, images, code block, bold, italic, and underline is all that is necessary. I don't bother with headers because that is what the upper levels of a nested, numbered list is for.Once you know what you're doing and the pitfalls to look out for (escape sequences, recursive nesting), it takes about 15 minutes to implement. The syntax is simple enough to include a key on the page used for editing. Processing is so simple that live-preview could be included if you want to get clever.   ;Quote:Original post by CygonAnd if you're using Microsoft compilers, you can even create your API documentation in the same way.Their C++ compiler has a switch that extract XML comment blocks from the source during a compile and writes them into a separate XML file that can then be displayed with an XSLT or even be transformed into a help file using Microsoft's "Sandcastle" tool.If you consider that proper documentation....   