Hi skazat!

Best advice I can give is: Get yourself a set of tools, and use all of them where appropriate. As long as you write your docs in a sytem that's portable, you'll be fine. It could be SGML/DocBook, XML, LaTeX, POD, HTML, etc. All of them are markup languages, and as such quite interchangable with each other by definition.

Personally, I use and like POD for smaller things. I wouldn't want to use anything else for module reference documentation. It's fine to document your modules, but I'd stay within that scope. I don't write books with it...

When it comes to Whitepapers, Technical Reports and the like, I use LyX. It's a graphical (xforms) WYSIWYM frontend to LaTeX 2e, and runs on X11, OS/2 and Windows/CygWin.

LyX exactly meets my requirements. As an author, I don't want to care (or be constantly tempted) to work on layouts, or formatting. I'd rather hack away on making a good point... ;) LyX does exactly that. It keeps my focus on the document structure and content, and let's me care about how the output actually looks (or which format it's in) only when I want to. It spits out LaTeX (of course), HTML, pdf, DocBook, Postscript. That's pretty much all I need.

Also, don't be scared by LaTeX complexity. You don't need to learn LaTeX to work with LyX. Not at all. However, if you're a bit like me, you'll maybe want to have a look into it. And since I did, I really feel the power under the hood of LyX.

Using Pod2LaTeX, you can easily translate your POD to LaTeX snipplets, which will be integrated into your LyX files with a few mouseclicks. They'll even "assimilate" your documents formatting!

Want grapics, fine, LyX will use almost any format. Math formulae? This is where LaTeX flexxes (heh) it's muscles! I love to have prettyprinted math formulae in my docs. A code snipplet is fine most of the time. But a neat formula often gives a better picutre about what your code does mathematically. Also make sure to get the Algoithms package for LaTeX. While not directly integrated in LyX, you'll learn how to use it with LyX in less than an hour. It'll pretty print your Perl code, with syntax formatting, line numbers, nice headers, list of algorithms page for your appendix, etc.

LyX print (postscript) output is excellent, especially compared to the minimal effort to archive it. You can't do that with Word.. ;)

What are LyX's weaknesses? Bigger tables can be a bit of a hassle, I miss a feature to automatically scale down the font sizes when the table becomes to large to fit (I'm sure there's some LaTeX way of doing so, however). Some things in LyX seem a bit complicated until you get used to them. LaTeX shines through the edges, which might trouble some people, for me however, it became one of LyX's strengths...

Maybe I slid a bit offtopic now, but maybe you want to bear with me. Another tool I really like is TCM (Toolkit for conceptual modelling). I use it for all my diagrams and modelling needs. Using it early in the development cycle not only provided me with diagrams for my docs, but also helped me design things in the first place, since there are diagram types with semantic checks built in.

The general diagram editor is all I need to add some "boxes and elipses with text in them, and some lines and arrows which connect the boxes" diagrams to my whitepapers (indeed, that's all I need to illustrate a problem). It also has a general table tool, that helps when LyX's tables won't suffice. It exports to EPS which is perfectly importable in LyX, and allows for scaling, too.

TCM uses a fully documented plaintext format, which can be automatically generated by some software. You can write Perl modules to dump your data structures as TCM files, if you needed that. If you want to see what TCM can do, read it's online docs. The diagrams you'll find there are made with it, of course.

To sum it up: POD, LyX/LaTeX and TCM are a powerful team, I'd reccomend to anybody who has to write technical documentation.

So long,
Flexx