My PHC wish list

Earlier this year I wrote a reference manual on plone.org. It was quite hard work (harder than I expected) and I finished it with a secret wish list of things I'd like to have had to make my life easier.

Writing turns out to be something I find difficult to collaborate on. Mainly because, although I start with a plan, the plan seems to change as the document evolves. Usually I know what I want to convey, but the best method of conveying it only emerges quite late in the process. Revisions can be pretty radical at that stage. This is what happened with the manual. It got reorganised several times over before I was really happy with the approach, and it was really hard to share.

I started writing it straight into plone.org, but pretty soon found that this wasn't the ideal medium for that kind of creative process. Several experiments later, it ended up in Word - with a version in Google docs for copy-editing and collaboration. I needed to be sure that terminology was consistent over about 80 (very short) sections, so search and replace across the whole was essential, and I also needed to be able to get an overview of the entire table of contents. Of course turning this back into clean HTML was a bit of a nightmare - involving Open Office and various addons.

So here's my wish list.

For the reader:

• I would have liked to be able to create a complete table of contents on the cover page, complete with short descriptions (rather like the Plone sitemap). I wanted them to be able to pin point exactly what they needed in the manual fairly quickly, but also see how what they wanted to know fitted into the bigger picture
• I would have liked a glossary, something that glossed common terms on the spot - either as a rollover or perhaps as a portlet on the side
• I would have liked a more distinctive set of consistent styles, enlarging the standard Kupu ones. A "warning" style, a "note this" style, a style for a set of step-by-step instructions - go here, click here
• I would have liked a way of showing the illustrations as a gallery

For the author:

• I'd like a ready-reference of consistent terms, spellings (style sheets, JavaScript) and stylistic standards. It turned out that it wasn't easy to get hold of the recommended style manual in the UK, and some of the conventions of punctuation were very different from those I learnt at school. Now I've been through all of that, I suppose I really should write it up for everyone else.
  
• I'd like to be able to search and replace across a series of pages
• I'd like to be able to link from one page to another
• I'd like to be able to keep the originals of my images somewhere, so that when things change, I've got the original images to go back to (or someone else has)
  
• I'd like to be able to generate some pages from a single set of data - some kind of quick and easy database to template solution (for the standard, quick-reference pages I did for each viewlet)
  
• Actually, really, I'd like to be able to drop one page into several different places....

That's it - oh yeah and a way to make Word write proper clean HTML.