Early on in the development of FUNDimensions, there wasn't any documentation, nor was there any definite intention to sell the product on the "open market"- it was just a simple custom project for a single customer.
When I contemplated selling FUNDimensions to other organizations, I knew I'd need a user manual. I was pretty horrified! I hated reading manuals, not because I don't like to read things but because they so obviously sucked. I often did read them to fulfill my capacity as a computer consultant, and that is how I knew they sucked, the acid test being that they did not contain the information needed to help my customer, or that information was difficult to find.
I certainly didn't think of myself as a writer of any sort, nor was there money to hire someone.
I chose to undertake the project of documenting FUNDimensions myself, as a special challenge and learning opportunity, inside of the risk that my efforts might not be useful, or even acceptable. I also used the project as an excuse to bone up on desktop publishing and technical writing software, which I expected would pay off in my consulting, since I work for several firms that do publishing as their main business. This boning up consisted of researching the best software for particular jobs, as well as learning to use the software.
I settled on WordPerfect at the start. It wasn't desktop publishing software, but a word processor. I pushed it to it's limits pretty easily: for example, I found it expedient to use a lot of screenshots with callouts. WP let me create these but wouldn't spellcheck the callouts.
Later I switched to Adobe Framemaker. It spellchecks callouts. It also could create a PDF file that already had bookmarks- you know, that list that shows up at the left side of some (larger) PDFs, that is so great for navigating the document and discerning the document structure. Creating these by hand, and recreating them every time you update documentation, would be a royal pain, so I was excited.
Framemaker has a reputation for a vicious learning curve. I read the manual for it, at 550 pages. Things like real cross-referencing, powerful auto-numbering of tables and figures, embedded hyperlinks (hey, this is about 1995!), and the ability to build cross-references, indexes and tables of contents across multiple files (chapters) was exciting to me. This was indeed a tool that could create excellent documentation, and allow for document updating with a realistic amount of effort.
I used a template that came with the program, designed for manuals. This helped me get up to speed and publishing with the program in a reasonable amount of time, by answering many of the questions Framemaker needs to ask before creating a finished document. Over the years, I have edited this template so much it is unrecognizable from it's parent, and so learned some of the extraordinary power of templates in Framemaker (and their potential in other software, too).
I really came to love working in Framemaker. To add to the pleasure, I selected a set of fonts for the user manual that would let me do "fine" typography, like ligatures, old-style numerals, small capitals, and the like. The adventure continued as I learned to use the fonts and develop my technical writing skills by building a library of books on typography and technical writing. One of the rewards was that I stumbled on Robert Bringhurst's The Elements of Typographic Style, a work that itself reflected the beauty of type in both form and content, and one of the best books I have ever read.
Adobe upset me when they dropped Framemaker for the Mac, having never ported it to run under Mac OS X. When new Macs couldn't run Classic anymore, I decided to get Framemaker for Windows running on the Mac under Parallels and Windows XP. That is what I just finished doing. I also needed to switch away from yet another orphaned Adobe technology, Multiple Master fonts. This required the most work. I had to edit every paragraph and character style, import the styles to every document (one for each chapter, and later, to ancillary documents, like the Client-Server Administration Guide), and carefully check the whole thing out.
I made some other changes, like using a little more color and contrast in certain text elements, adding a running header for the chapter section, and cleaning up some template, style-sheet and auto-numbering inconsistencies that had made maintenance of the document more difficult and error-prone.
The text was also updated and revised. For example, there were several places I'd forgotten to update when FUNDimensions shipped with it's own backup module, that still recommended Retrospect software.
The process was hampered by the fact that, even though I used Adobe's own OpenType fonts and the latest version of Framemaker for the move to Windows, Framemaker still couldn't access the extended character sets in these fonts. A hack allowed me to create new fonts that consisted of the extended characters located in the places where the ordinary characters would be, making it possible to preserve the fine typography I'd spent considerable time setting on the Mac.
In spite of all the glitches, it was still kind of fun and satisfying, this typesetting and designing, and experiencing the power of Framemaker and other tools (Acrobat, GraphicConverter, SnapzPro, and FUNDimensions itself running to provide the source for screenshots) to render something possessing a certain kind of perfection.
Generally, Framemaker 8 is a mess. I've encountered all manner of bugs, crashing and otherwise, and the minimal support for OpenType is positively alarming, suggesting that Adobe isn't very serious about Framemaker, or that the code is inflexible to adopting OpenType, or both. I often think I'd like to create a Framemaker knock-off, "done right". I love the program, but hate it's publisher.
If you'd like to look over my efforts with documentation, totaling about 500 pages, they are all on the web site at this location (brief form required). Post your comments right here. Thanks.
