Re: quo vadis, docs

[Davyd Madeley <davyd madeley id au>]

On Mon, 2009-02-09 at 21:37 +0000, Matthew Paul Thomas wrote:

> More good news: That's also often unnecessary. A description of a 
> feature in checkbox-by-checkbox detail is just as boring to read as it 
> is to write. Instead, think: What are the most likely reasons someone 
> will have trouble here? And what things are people most likely to be 
> looking for under a different name? Answer those questions (without 
> phrasing them as questions) in two or three paragraphs each.
> <http://tinyurl.com/clrt3o> Do that, and you'll have something more 
> readable and more useful than ye olde Gnome Application Manuelle V2.7.

Matthew is right on here. Element by element UI description rarely do
anything to help the user.

Instead I like to focus on "task oriented" documentation (opening a
file, making changes, saving a file, making a backup). Try to group
related tasks into sections, and try to put them in an order that the
user is likely to need them in. Cross reference to more in-depth
discussions if required. Include sidebars with information to educate
and empower the user, using analogies and objects they can relate with.

Your documents can still atrophy as buttons and labels change names and
marks drawn on UI screenshots no longer resemble the current UI, but a
lot of the prose will still be relevant and ideally even useful.

--d

-- 
Davyd Madeley

http://www.davyd.id.au/
08B0 341A 0B9B 08BB 2118  C060 2EDD BB4F 5191 6CDA