Automated Documentation in PHP

I’ve been looking for some software to help me compile web-based documentation for a school that we work in.

What they are trying to do is write coursework modules for staff to follow, and then have them available on a site.

I know how this ends up. One of the ideas I had when they told me that they were writing modules was to put it all in word, and then generate PDFs at the end, using the headers for bookmarks in Adobe.

It was sound until I was told that there must be ‘no scrolling’, so that pupils with a 2-second timespan might be able to read it. I’m not convinced that the no-scrolling is the way to go, but I suppose it’s no better one way or another.

So, here we are. I’ve scoured the internet looking for something that will do the job nicely. I found some modules on the PEAR site that would allow me to create documentation and store links in a database. I liked the look of it, but it seemed that I might have been going a little off-track as with HTML Menu, I’d probably end up storing all of the data in HTML pages that I’d still manage and then place the menu in a database. Not fun.

Luckily, an offshoot of a PEAR project surfaced called PHP Dcoumentor while has some useful documentation (surprise, surprise), and seems to be able to generate documentation into a variety of formats from XML or DTD, which can’t be bad.

Steve was perplexed as to why we are doing this, when it means that we would have to go through everything that the tutors have written for the modules and reformat it. Ironically, if they had settled on my PDF idea in the first place, then it’s feasible that we could have used the Word styles as a starting block for the online styles.

Still, if someone wants to pay me to make documents look pretty, then I’m all for it.