Preface Matter Minimalism

I’m not a fan of prefaces. I think they are just noise standing between the reader and the information he seeks. I really, truly hate “conventions used in this guide.” If you need a table to explain the conventions used in your guide, then your conventions probably suck.

However, I do feel the need for a brief statement of what the product is intended to do (not a big marketing blurb), and a description of the scope and intended audience of the guide, and — finally — information about what other user assistance resources are available. 

Interestingly, I’m looking at an Administrator guide that has that information on the front cover. Turn that page, and what do you have? Content! (Actually, the table of contents.) There’s not a single page of preface. It’s nice. I think I may go with that. 

Off-topic: This publication is clearly intended to be viewed online. The left and right margins are about .5″ It looks fine online, but it’s pretty annoying as a printout. The content is lovely, though. It’s been a long time since I read a user manual and thought the content was lovely.

I do like startups, but I don’t like Word

Happily, my “vacation” lasted exactly 4 weeks, to the day. I’m on my second day at a rather small SaaS startup. I like so many things about it, from the funding partners to the office space (gorgeous, easy commute). What I don’t like about it is that they are still using Word. This isn’t unusual, of course. The last startup I was with (the one I was laid off from) was using Word when I arrived. They were very receptive to me making any and all changes to their documentation, so the first thing I did was buy FrameMaker. This was convenient b/c I was completely dumping all their previous documentation and starting from scratch, so there was no painful Word-to-Frame conversion.

Here, there’s a pretty small amount of documentation in place. When you take redundancy and un-helpful screenshots into account, we’re probably talking about 100 pages. We expect that to grow considerably, so I would really like to talk them into buying FrameMaker or (maybe) the Technical Communication Suite.

I know why *I* prefer FrameMaker: the ease with which it supports the template I created, which is Information Mapping-like in some ways, if I’ve got to narrow it down to just one reason. Designing the same template in Word is difficult and has some elements that simply cannot be reproduced.

I’d love to hear what pfoduct you prefer for longer technical documents and why (longer being more than 30 pages, to me).

Here’s a link to an article comparing Frame and Word. Word doesn’t come out looking too great It’s a little dated; some of his complaints about Frame have been addressed in more recent versions.

http://ivanwalsh.blogspot.com/2006/04/microsoft-word-compared-against-adobe.html