Writing a manual can be fun, or it can be tedious, but it’s usually a combination of both, which is where I am right about now. But Fun Land is now clearly visible in the rear-view mirror.
At this point the guide is 64 pages long, and it’s pretty much content complete. 64 pages for a program that has a total of 8 windows or so, and maybe 30 controls. Shouldn’t this thing just say “install, and have at it—best of luck, we’re all rooting for you”?
It’s not so much the UI that needs so many pages: as you (may) know, I’ve tried to make the UI as simple as possible. And I think I’ve done a decent job with that. But you can do a lot of things with that UI, and those things are often nerve-wracking, and performed by users who have never done anything like this before or—if they have—they’ve never understood what they were doing.
In the new guide, I’ve reworked much of the existing material, and have added more based on the common questions and tasks I’ve seen users do over the past year or so. There are many sections right up front that cover these common tasks, and I’ve tried to answer the common questions about those tasks right in the section.
Each can pretty much stand alone, and be read without referring to the remainder of the guide. So, there’s some repetition, but I hope it improves the usability of the document. Not that there was anything terribly wrong with the existing User’s Guide—we’ve had great feedback on it. But, constant improvement, in all things. No stone left unturned. Except maybe the about box. Maybe.
What’s left is lots of proofreading, tweaking, and re-shooting a huge pile of screen shots.
And then, when the whole thing is finally locked down, Adobe Acrobat hell.
As I said in the previous post, Acrobat, on the Mac, doesn’t automatically take the structure of a document, and cross-references therein, and generate appropriate tagging for PDFs to produce the nice table of contents and hyperlinking that a long document, like this one, needs. Which sucks. So, my last task is taking the large number of cross-references—which all had to be hand-formatted to look like hyperlinks—and manually tag the PDF to support them. And then, tag the whole thing to generate a real table of contents that’s separate from the main text.
Needless to say, by the end, I’ll be well into Tedious Territory.
14 Nov 2005 at 08:09 am | #
i bet you’ve already thought of this, but, is it possible to move the pdf you’re working on to a Windows machine, install a trial version or something of Acrobat, and use it to create the pdf with all the links and stuff so you don’t have to do it by hand?
your hard work in this makes me want to read the manual all the way through, just to appreciate your efforts.
i writhe with anticipation
14 Nov 2005 at 08:22 am | #
Well, it’s not exactly writheworthy, Steve, but it’s certainly improved.
I have thought of moving it to Windows and back, but in the end want to do the whole thing on the Mac… and I don’t feel right about using a demo version that way. (It’d be nice if my existing Acrobat license was cross-platform, though...)
15 Nov 2005 at 01:57 pm | #
Adobe Acrobat—I know Adobe brought us the pdf, but I still think Acrobat sucks. Nothing takes longer to boot on either my mac at home or my PC at work.
Best of luck on that manual, Dave! They say the only thing more delightful than reading a technical writing is having to write it.
I must say that your last manual was absolutely fantastic and should win some award for most user friendly, clear and readable technical writing on the planet. If only others followed your example . . .