Writting documentation [revisited]

A few days ago I have mentioned my ramblings on document generation tools. After trying the solutions described in the post (except the solution suggested by Andreas Mecky and Matt Raible, not because I do not like it, but I am still waiting for the Eclipse plugin), this morning (in fact an hour ago) I have started to write down my proposal for document generation solution. A few minutes later I was disturbed by the sound of my mail notification: a comment was just posted on this blog. Subject: Generating project documentation. Suggested solution: Apache Forrest. So I saved the few lines I have just written, fired Firefox and here it goes: Apache Forrest. I few minutes later a demo site was generated automatically by Forrest. , which did in background some interesting stuff (created the documentation directory structure, copied some document templates and a skin and voila!).
A quick look in the internals of Apache Forrest revealed that it uses xdoc as page sources (it even gives you some DTDs), offers an Ant build file (damn this is nice [smile/]) and includes some site templates which are quite clean. The first two arguments are encouraging me to continue investigating (they are according to my goal – but about this I will write in the Writting documentation [final] later). I have to pass again over all my requirements and see how Apache Forrest behaves, but for the beginning I must say I am quite satisfied (even more than satisfied [smile/], and so I was joking about disturbing: thank you very much Anonymous for your suggestion. Please come back to see what’s happening next [blink/]).
Unfortunately this will make me be a little late with the first public release of the new and cool rjxconfig tool, but be sure that when I figure all about generating site documentation it will be here!

1 Comment

Filed under Tools

One response to “Writting documentation [revisited]

  1. David

    Instead of jumping to the tools, why don’t you spell out what comprises project documentation.

    Once you know what you need to document, then look for a tool. If you want to document an API, then doxygen. If you document an external API, then RSS it whatever it is. In fact, get it into XML one way or the other. Then, RSS it. The document could be a series of blogs.

    Are you printing it out? Is it Agile or waterfall or spiral? Are you documenting the requirements? Then, what about traceability? Do you negotiate with others about requirement conflicts and responsibility allocation? Do you already use UML for internals?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s