Document-generation software, part II: how should them be?

You already know the story:  your company is growing and you need standardized tools to generate help manuals, FAQs and technical manuals in multiple languages. Maybe, just maybe, you are a computer-savvy user already, and even tried free alternative like LaTeX or Docgen yourself.

But let's face it: some tools are very time-consuming. Do you really want to get a book to Learn LaTeX or to face the limited quirks of Docgen?

No, I'm sure you don't.  Therefore, document generation tools should be easy and reliable to use, and provide a minimum learning curve.

How a document-generation tool should not be.

• A good document-generation tool should not be outdated. Take a look at Docgen again. As you can see on their site (http://sourceforge.net/projects/protege-docgen/) the last update was two years ago. That's a lot of time! Who knows how many bugs are lying right there, waiting for some hacker to get them exploited?

• A good document-generation tool should not have a bad support team. And this is not just the problem of Docgen; many open-source tools, as LaTeX or Doxygen, have an informal support team that consists, basically, of technical members – usually developers of the project themselves. That would be all nice and great, except for something: they hate when laypeople ask them "dumb" questions. Well, newsflash: of course they are "dumb!" The developer knows everything about the project, and the user just to generate his report and be done with it. He certainly does *not* want to look at the project's source code just to figure out some obscure functions.

• A good document-generation Tool Should not be filled with half-baked tools. We've seen this everywhere – even in commercial software. Now imagine the world of *free* software: it has the same problem, except it is multiplied by tenfold: LaTeX, for instance, requires you to be proficient with a text editor. If you aren't, well... you can use some interfaces like Lyx, but beware: your source text may misbehave, the manually inserted formula you just posted might give you the wrong output, and the templates are just plain hard to modify.

• A good document-generation Tool Should not be hard to use. Again, this is true when it comes to most of the document-generation tools out there, both open source and commercial: they might require that you spend time on IRC (Internet Relay Chat), hoping that some developer will be there, answering your question – which is usually urgent, as you have business to do, too – and then, he asks, have you seen the [outdated] documentation of our project? Or worse: you can hear things like, just google it, or RTFM (search this one out and see what it means; it is not something nice). And be certain of one thing: if you rely on these tools, you might end up reading this words on IRC a lot. If you are fired by your boss because you spend a lot of time "chatting" (which it obviously isn't true), don't say you were not warned.

But then... how should a good document-generation tool be?

• A good document-generation tool should focus on the user, not on the developer. And yet, many developers seem to ignore this, which is truth not only to these tools, but it the basis of well-developed software. If you are developing software for an artist, you must think like an artist; if you are developing software for a book publisher, then you must think like a book publisher; and, obviously, if you are developing for people that want documents generated without concern of how they should look like, how should you develop a this piece of software? Yes, exactly: with the user in mind. If you ever meet a developer and he talks to you about a killer feature, then ask him this: "well, how does this killer feature helps me boost my productivity?"

• A good document-generation tool should have a low learning curve. This has been discussed before, but it cannot be stressed enough: people that look for document-generating software are looking for something that will generate beautiful, quick documents for them. If they have to spend 6 months just how to generate a document, then what's the point? They could just grab a word processor or a presentation tool and do it themselves, and it would be faster and more productive.

• A good document-generation tool should have a well-trained support team that speaks the language of its users. Again, this sounds obvious, but believe it or not, many projects (and commercial companies) forget about this. A well-trained support team should speak the language of the user, and not force him/her to do the opposite. Furthermore, check if the software you want to download / purchase has online support: it's certainly useful if you do get stuck at some point while doing your tasks.