Re: Documentation Standards?

[Rose Wilcox <RWILC -at- FAST -dot- DOT -dot- STATE -dot- AZ -dot- US>]

     Danna McLaughlin writes:

>     I'm trying to learn more about developing standards for a small
>     documentation department (three writers). We put out hundreds of pages
>    per month. We have worked for a while with unspoken standards, but we
>     sometimes end up with several related procedures that use different
 >    words to explain the same task.

We have the exact same size of a team (three writers).  I find unspoken
standards very difficult personally, because I don't remember all of them.
 It's nice to have a document or two to look them up in when I forget.

>     Is this breed of inconsistency confusing to the user, even if a very
>    basic action is being described? For example, is it okay to tell
>     someone to "enter the value onto Screen 35" in one set of instructions
 >    and then tell them to "type the value onto Screen 35" in another set?

It can be, depending on the specific example.  Consistency is important, but
you may need some leeway if your application varies from the programs the
other writers are documenting.

>     Has anyone out there dealt with these issues?
>    Has anyone developed a set of standards from scratch? If so, how did
>     you go about it?
1) Choose reference materials such as a Dictionary, Computer Dictionary, and
Manual of Style and agree on them as baselines.  2) Have one person be
responsible for collecting and recording the team agreements on styles,
formats, spellings, etc. not covered by the baseline references or needing
to diverge from the baseline references because of your application.  3) Use
meetings, email, sticky notes, and all the other tools of the trade to bring
up and document agreements.  4) Do regular "peer" reviews of all your
documents *before* sending them outside of your department if possible.
 That way you will find areas that require agreement and learn from each
others' writing styles.

>    Should this be a democratic event, or should one person lay down the
>     law?
Always it should be democratic.  It should be done by synergy -- consensus
should be reached if possible with a team of only three people.  (Not
possible in a larger team.)  Possibly there should be a team lead to decide
in case all three people cannot agree, but if the two other writers agree,
the team lead should let their votes decide the issue.  If the three writers
are all pretty good, one can sway the other two *with a convincing
argument*.   If your argument does not convince the other two people, then
your decision is either not as good or you haven't articulated your idea
clearly enough.
After the writers agree and formulate the product, outside edits, especially
user testing if available, should be allowed to influence your standards --
if the outside editor has a convincing argument :-).


 >    How much leeway should an individual writer have when it comes to
  >   wording?

This depends on your audience and the application.  So far my team of three
has been able to agree on areas where the individual writer should have
leeway -- so these areas are decided by democratic process also....  If your
audiences and applications diverge widely the writer needs a lot of license.
 If not, take it on a case-by-case basis.  One caveat:  the writer should be
consistent within the document he or she is creating.

Rosie Wilcox (Northcrowe)
rwilc -at- fast -dot- dot -dot- state -dot- az -dot- us
ncrowe -at- primenet -dot- com
"Brevity is the soul of wit."
             --William Shakespeare