OSDev.org

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

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

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

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

Customer Service?

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

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!

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.

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...

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...

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

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.

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.

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.

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.