Have you ever told a project manager that the instructions he plans on releasing with an application -- instructions written by an intern who is here for a three-month stint -- are complete junk and that it would be an embarrassment to the organization to give them to users? When you tell a project manager that, surprise, you win yourself a new documentation project.
That's all right, because Joomla, the topic of the instructions, is something I've been wanting to explore in depth. I have to say, I'm pretty impressed with Joomla. As a content management system, it's powerful, easy to use, and captivating (kind of like driving my new Nissan Altima 3.5).
As I rewrote the Word document (of course it was in Word), I decided to create it in InDesign. In a time when I keep hearing about content re-use and single sourcing, a lot of my projects are small, with just one deliverable needed, intended for a handful of people, most of whom prefer something brief. Rather than the one or two page quick reference guides that I usually push, I've been extending them to 8 or 16 page documents.
Working with InDesign is interesting. On the one hand, it's not really a tool built for technical writers. It's intended for people laying out magazines, brochures, other heavily designed print matter. As such, some things can be confusing. Cross references, figure references, a table of contents -- get ready to search the help to figure these out.
On the other hand, the power of the InDesign is somewhat captivating. You're only limited by your own ignorance. Every day I learn something new and say, hey, that's cool. For example, I installed the Typefi Autofit plugin yesterday afternoon to enable auto-expanding text frames, which I specifically wanted for my note styles. It's neat that a proprietary application like InDesign has so many third-party plugins.
You may feel that some of the applications you use are boorish and dumb. Not so with InDesign. InDesign is an application with intelligence and sophistication. When you learn it, you feel like you're part of an elite club.
When you can't figure something out, the Adobe Forums for InDesign are excellent. Unlike Feedburner's forums, which are a wasteland of single cries for help with no responses, the InDesign forums are active, monitored by gurus, and you get informative responses within an hour.
But enough about InDesign. The real question is why bother to use such a powerful layout tool when I could create the content in Flare (or some other HAT) and single source to a printed output? That's certainly an option, but styling the printed output from Flare doesn't compare with the styling options in InDesign (at least not within my print CSS skills in Flare).
Also, when I'm writing in a HAT, I get the sense that space is unlimited. I write every little detail, adding topic after topic. I think of every possible scenario and question and document it. The result is a printed document or online help file that is not really readable anymore due to length. It can only be searched.
I know it may be an old-fashioned concept, but I think users want a short guide they can read. Sure, users want to search for answers to those arcane questions, but they also want a guide that's feasible to get through, that isn't a War in Peace type novel but rather a dozen pages that tells them what they need to know. When it's under 20 pages and well-designed, with a readable, attractive layout, that's a product that has high value for users. It's a deliverable that project managers and other techies can actually review. As a user, it's something that still fits into your life.
If you give someone a manual that makes an almighty thud, they don't even open it.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.