[boost] Documentation Wizard

From: Rob Stewart (stewart_at_[hidden])
Date: 2005-10-27 17:20:33

Quite some time ago, Dave Abrahams announced that I was the new
Boost Documentation Wizard.  I said I'd write something on the
subject and that is long overdue.  Herewith, I describe what I
think the DocWiz should do and what is needed from volunteers to
make it happen.  That is, I'm trying to document the new DocWiz
role and solicit your help.

Please have a look and comment on what I'm proposing.  If you
don't like the direction I'm planning, say so.  If you think I've
missed something, let me know.  If you think you can help in some
way, please let me know; I can't do the job alone.

The DocWiz's purpose is to try to foster better documentation for
Boost.  Since this is something new at Boost, some measures will
be grandfathered* of necessity, while others will likely be
retrofitted to existing documentation.  Some things will be
purely stylistic, but most will be substantive.

A significant problem with writing library documentation is that
English is often not the library author's primary language.*  It
is all too common that those who can write C++ fluently cannot
write English well.  Thus, we need a means to ensure that the
library author's ideas are well communicated.

Another problem with writing library documentation is knowing
what to write.  How much detail is sufficient?  How many code
examples should there be?  How much material should be relegated
to a reference section and how much should be presented in a
tutorial?  What is a sufficient rationale for the library?  Many
of these issues can be addressed by seeking insight from what has
been written well already and by seeking advice from those expert
on the tasks.  From that information we can capture best
practices to assist new documentation authors.

Still another problem is consistency.  As Boost grows, having a
reasonably consistent look and feel to our documentation becomes
increasingly important.  Naming and organizing sections in our
documentation must be consistent across libraries to simplify
locating desired information in each library.

Given the rate at which new libraries are proposed, I cannot do
this task alone.  I'm the father of eight (yes, 8!) children (so
far, at least), I have a full time job, etc.  Like everyone else,
I'm quite busy.  Thus, I need help.  I intend to be the manager
of a group of folks who can divide the workload to make it
manageable.  To that end, I propose the following positions to
assist in improving the state of Boost documentation:

   Editors - Folks with demonstrably good English skills who can
             assist library authors by clarifying and correcting
             the documentation at various times, as determined by
             the author, so the meaning is clear.  Editors also
             advice the author on structural changes necessary to
             conform to Boost guidelines.  Editors are not so
             much concerned with content as with clear
             communication of what is included.

   Domain Experts***
           - Folks with special skills in writing certain types
             of documentation such as concepts or tutorials; when
             a library author is struggling to write a portion of
             the library's documentation, the author can call
             upon the appropriate domain expert for assistance.

   Mentors - Folks with skills and desire to write good
             documentation who can come alongside a new library
             author to ghost write, share writing tasks, suggest
             content, etc.  The output from author/mentor
             collaboration must still be approved by an editor.

The workload of an editor will be varied since the number of
authors writing documentation varies and based upon their update
schedules.  The workload of a domain expert should be quite low
as folks writing concept descriptions, for example, should not
need a domain expert's input often or long.  The workload of a
mentor likely will be as high as the mentor wishes.

Initially, anyone acting as an editor will need to prove his/her
skills by relying on trusted editors to proof the results.  Once
proven, a new editor can act autonomously.

The expected result of this group of folks is documentation that
is acceptable to Boost.  I propose that a library cannot be fully
accepted by Boost without the DocWiz's approval.  IOW, a library
can be conditionally accepted pending documentation approval.
(That approval may be given based solely upon the word of a
trusted editor; the DocWiz needn't read every document to give
approval, but the responsibility does lie with the DocWiz for
deficient approved documentation.)

Note that the DocWiz is not the final authority on what is
acceptable documentation.  Users of that documentation are.  An
author will likely need to update documentation based upon user
experience.  Such changes should be subject to an editorial
review, too, in order to maintain high standards.

--------
* That means that existing documentation needn't be changed to
  conform to new policies, but may be if the author chooses.

** Another problem is that English *is* the library author's
  primary language. :)

*** The name "domain expert" smacks too much of someone who is
  expert in the domain of the library rather than of a particular
  aspect of library documentation.  Please suggest a better name.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;