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.
---------------------------------------------------------------
4 comments:
A very fundamental question: Why do you need a linear document called the Installation Guide?
Create a simple wizard that lets a sys admin chose his/her specific scenario.And when they click Finish, your Help app will show them the steps they need.Nothing extra.
Ok..this comment is being typed after a sunday siesta.So, tell me if its crap :)
Kumar,
Me too after the Sunday siesta, so maybe still a bit woozy...
We do have a wizard, and it's pretty simple and after Finish, you only need a couple of more steps (for configuring). The problem begins when sysadmins choose the non-automatic method (many do) which has several post-intsall steps that need to be done manually. The second problem is - the install typically happens on more than one machine, so post-install, one would still have to configure the components A, B, and C to talk to each other.
Me, being a non-geek, used the wizard to install (and configure) everything on one machine and it works like a dream - but that's not how all real-life customers do it - they have bits and pieces spread all over...
A thought (not a solution; not even a suggestion):
If I were installing the product, I'd have preferred a guide with the OS as the first level and RDBMS as the next level of separation (because the environment is already fixed before the sys admin steps in). When the sys admin comes in, each has a way of doing things: So, the separation of automatic or manual. Then, of course, the components in the required order (with installation and configuration of each.)
The structure can be mentioned as prominently as possible (in a flow chart with links) at the introduction of the guide.
Sharada,
Your spoken-aloud thought is what the current ToC looks as of now: platform > RDMS > branch1 (manual) or branch2 (automatic). There's also a before-you-start table that lists the flows and branches.
But people still said the ToC was confusing.
I am slightly at my wits' end trying to think of all the permutations-combinations and trying to make the install guide as consumable as possible.
Post a Comment