[Gluster-users] Meta-discussion

[Jeff Darcy]

On 1/2/13 8:38 AM, Whit Blauvelt wrote:
> But something on the scale of Gluster should have someone hired full time to
> do nothing but continuously write and update documentation.

I think we do actually have someone working full time on documentation, but
"documentation" in that sense mostly just means manuals.  What I hear from
users is that there's a mostly separate need for other kinds of documentation,
for example:

* A general "principles of operation" guide - not a whole book, but more than
bits scattered among slide presentations and wiki pages.  Let's say something
that would be on the order of 15-50 pages printed out.

* Many "cookbook" examples detailing initial configurations for common use
cases (e.g. media servers, VM storage) and higher-level sequences of steps for
common operations (e.g. adding servers).  It's nice to have reference material
describing the individual commands, but there are common sequences that should
be documented in more of a "story" form.

* Documentation (or even better tools) to identify common known problems in
plain English instead of requiring people to interpret cryptic log contents.

Unfortunately, most of these require developer-level (or architect-level)
knowledge of the system, so it pretty much has to be developers (or architects)
doing the majority of the work.  Given the amount of time involved, it does
have to be at least a half-time assignment for one of the people currently
assigned full-time to development, and that commitment just hasn't been made yet.

Am I misunderstanding what's needed here?  Or how to address it?  I'd be glad
to act as internal advocate for more along these lines, but first I need to be
sure that I understand what would really help users.