Documentation formats

JamesM · Post by **JamesM** » Sat Oct 06, 2007 4:09 am

What format do you guys use for your documentation?

I was wanting to use a structured, xml based format like DITA/DocBook, but the rendering toolchain is SERIOUSLY complex and XSL stylesheets are a nightmare to change.

Just wondering

Zacariaz · Post by **Zacariaz** » Sat Oct 06, 2007 4:16 am

Real men dont read manual or documentation, thus theres really no nead to write any

JamesM · Post by **JamesM** » Sat Oct 06, 2007 4:36 am

Hmm... right then. I assume you don't work in CS for a living?

Zacariaz · Post by **Zacariaz** » Sat Oct 06, 2007 5:37 am

CS? Whats CS? Since in dont know i supose i dont...

Tyler · Post by **Tyler** » Sat Oct 06, 2007 6:30 am

Customer Service?

JamesM · Post by **JamesM** » Sat Oct 06, 2007 6:35 am

Well, I was referring to Computer Science - was that Customer Service reference a joke or an insult?

Tyler · Post by **Tyler** » Sat Oct 06, 2007 6:57 am

Actually it seemed logical, given that people don't work in Computer Science, and good Documenation is useful for the Customer Service Departments.

So, i'll say, it's the Joke one!

JamesM · Post by **JamesM** » Sat Oct 06, 2007 10:51 am

Oh, OK - You thought I was referring to "computer science" in academia only? That term can encompass pretty much all development jobs.

Back on topic, I was looking for documentation formats.

earlz · Post by **earlz** » Sat Oct 06, 2007 11:10 am

I mostly just use somethign like OpenOffice to make stuff, and then export it to PDF...but, you may also wish to do somethign like that, and then export to html...

I'm pretty simplistic though...

JamesM · Post by **JamesM** » Sat Oct 06, 2007 11:22 am

Yes, I did have that idea. I would like something a little more structured however.

I'm erring on the side of wikimedia format atm: my project is hosted on googlecode which has built in wiki pages...

JackScott · Post by **JackScott** » Sat Oct 06, 2007 11:14 pm

Have you looked at TeX / LaTeX? It's pretty well structured (that being the whole point of LaTeX), and exports to PDF so all the 'normal' people can read it.

http://en.wikipedia.org/wiki/LaTeX

AndrewAPrice · Post by **AndrewAPrice** » Sun Oct 07, 2007 12:32 am

Have you looked at Microsoft Assistance Markup Language? It's sort of XML based, and there are several tools on the Internet to covert it to HTML and PDF.

Solar · Post by **Solar** » Mon Oct 08, 2007 8:31 am

Personally I use a Wiki for creating / updating / keeping dokumentation alive, and export to HTML for snapshot / distribution. For something beyond hobbyist use, I'd prefer PDF, as HTML doesn't allow for easy hardcopy and makes full-text search a pain.

Everything else is a PITA, IMHO, because it forces people to install / use software they don't have on their system already.

For PDCLib, which is pretty code-centric anyhow, well-placed comments and a Readme.txt must suffice.

JamesM · Post by **JamesM** » Mon Oct 08, 2007 8:59 am

Thanks guys. I've gone for using DocBook format (based on XML).

The developer must install a toolchain to build the docs, but that's easy enough and I've documented it already. It exports to PDF, XHTML and man pages and I've just hacked together a script to make GoogleWiki code from it so I can put it on my wiki pages at googlecode.com

Cheers for the input.

AndrewAPrice · Post by **AndrewAPrice** » Mon Oct 08, 2007 7:10 pm

I found Doc-o-Matic really cool. It can export to HTML help files (there are lots of viewers for Gnome/KDE on Sourceforge), plain HTML, PDF, and some other formats.