Two, unfortunately common, anti-patterns in documentation of systems
and standards. I am pretty sure anyone who open a manual for a software
system came across the first of these. The second is a bit more subtle,
thus a bit more of a headache.
The Copy-Paste AntiPattern
This doesn't refer to documentation writers using copy & paste.
This refers to documentation writers documenting the trivial (e.g. copy
and paste functionality) while neglecting to document the meaning
behind the system. How many time have you decided to bite the bullet
and RTFM, only to discover the the F is really descriptive of the M?
How many time have you been presented with a dialog containing several
fields, and the help page for that dialog contains the most inane
documentation on how to click 'OK' to approve your choice, but click
'Cancel' to close the dialog with no changes... but no clue as to what
choices you can make and their effect of the system?
Party this is our (developers) fault, for not really providing the tech
writers insights into the bigger problem domain and our solution.
Partly this is the tech writers fault, as they try to justify their
salary.
The obvious answer is to teach the tech writers what the system tries
to achieve and why (and not just provide screenshots), and make them
understand that our users (barring blond moment) know how to operate a
computer.
The less obvious answer is to build applications that do not need to be
documented. This doesn't mean just not documenting it. It means that
people using it - with perhaps the help of a short screencast - will be
able to "get it". Use Conventions - the human brain is wired to
recognise patterns; Balance your User Interfaces - clean, simple and
fully functional.
The Abstract Example AntiPattern
This one is a bit more tricky to explain. Imagine you read a standard.
Imagine this standard contains a complex generalised mechanism to
handle a particular problem. Imagine the standard authors were aware
that this is a complex generalised mechanism and wanted to provide you
with an example to better illustrate what they mean. Now think back of
such time and remember how many examples were of the type:
Huh. So they were talking simply about transforming a distance to
speed. Oh! so they whole thing is about transformation of parameters.
Well, why didn't you just say so?
So when you do need to provide an example, try to give a concrete real
life example of how you use the standard. Do not provide an abstract
example to an abstract concept, it doesn't help much only further
obscures your aim.
Previous Topic
