This post has a post script written about 45 days after the original post. And a second postscript almost six months from the original post date.
---------------------------------------------------------------Early this year, I wrote the install guide for an enterprise-level reporting application. The application itself is pretty easy to use - once it's installed properly - with intuitive UI elements etc. It's the installation that's a bit complicated. The product has three separate components which, while they can be installed on a single machine, will in a real scenario be installed on three (and possibly four) different machines. Let's say the components are A, B, and C. The installation order should be, in sequence,
- Install and configure A
- Install and configure B
- Install and configure C
and the expanded ToC looked like this:
Thereafter, things got murkier. A and B ride on top of pre-installed RDMSs, which effects the configuration steps. The installation itself has two threads - manual and automatic - which further complicates matters....Version 1.0 of the product was releasing, like, day-before-yesterday, and without much time on hand, I ended up with a document that had the following ToC:
Every time I looked at it, I puked. But my dev team loved it - they found navigation a breeze and assured me that it'd be sysadmins who'll be reading such install guides and sysadmin minds work pretty much like theirs, and NO, it would not be a problem for the reader.Two months into the release, the product is well-received, we're working on an upgrade and feedback starts trickling in...the install guide has all info but it's difficult to figure out what is located where...once I am at a page, it's difficult to figure out what's Next and Prev...there are too many "related links" on a page and I get confused (this last bit is not my doing - it's a DITA thing. All subtopics in a "family" or a "sequence" topic get automatically linked to each other).
In short, nope, sysadmin minds were not working the way the dev team said it does. I pretty much suspect a glazed look came over their eyes when sysadmins expanded the ToC and saw all those nested and more nested topics. I also suspect none of the sysadmins read the checklists and high-level steps I'd included in the "Planning the installation" topic.
In this post, I am thinking aloud about restructuring the ToC. Here's what's on my mind:
So, instead of readers navigating like this:
they can now navigate like this:
Am still thinking, though, if there's a better way to present the information...---------------------------------------------------------------
Post script 1 dated November 6, 2009
I am leaving the ToC alone. What I'm doing is pulling out a buried topic and moving it right to the top, plus calling it prominently in the default home page of the online help. This topic has an installation matrix, and road maps for common deployment scenarios. People, when pointed to this hitherto-unseen topic, exclaimed, "Thanks! This is tremendous help."
Lesson learnt (from Post Script 1 response)
Findability is important. In-your-face findability is absolutely important.
[aside]"She dwelt among the untrodden ways...Half hidden from the eye! Fair as a star..." [/aside]
Post script 2 dated March 10, 2010
Because the road map was such a success, we're toying with the idea of automating it - answer some questions about your deployment setup and get an on-the-fly custom install guide.
---------------------------------------------------------------
