Re: creating documentation

An option, if you can arrange it, would be to get someone else to write it. Seriously. If you can find someone who's (a) good at writing, and (b) amenable to helping, then get them to set the system up and document what they're doing at the same time (with your assistance as and when they need it). Ideally, get more than one person to set the system up, so you cover as many 'gotchas' as possible.

And, yes, I realise that that "If you can find someone..." sentence may possibly be a tad optimistic ;-)

Another alternative, which I personally think works really well, is to have either a Wiki or user-commentable documentation (see AnnoCPAN for the sort of thing I'm on about). Admittedly it can be more long-term work in terms of keeping the content useful and/or spam-free, but, assuming your users are in any way "involved" with the system, then that may work really well for you.

Comment on Re: creating documentation

Replies are listed 'Best First'.
Re^2: creating documentation by ww (Archbishop) on Dec 27, 2005 at 12:27 UTC
john_oshea's first suggestion really hits home. As the developer, one "knows" what one builds into the package, but some of the features you include may be obscure to the various users he mentioned... whether because your descriptions -- as accurate as they may be -- don't "ring any bells" for some of them or whether your docs fail to spell out some feature or capability that's obvious to you but doesn't occur to them. And even if you can't find the writer he described, watching and coaching others thru the setup/use may greatly improve the documentation, as might the wiki approach, though I would fear that most contributions there would come from the more technically-inclined, leaving some end-user questions unanswered.	[reply]

Replies are listed 'Best First'.

Re^2: creating documentation
by ww (Archbishop) on Dec 27, 2005 at 12:27 UTC

john_oshea's first suggestion really hits home.

And even if you can't find the writer he described, watching and coaching others thru the setup/use may greatly improve the documentation, as might the wiki approach, though I would fear that most contributions there would come from the more technically-inclined, leaving some end-user questions unanswered.

[reply]