[Gluster-users] Meta-discussion

[Sean Davis]

On Wed, Jan 2, 2013 at 9:03 AM, Jeff Darcy <jdarcy at redhat.com> wrote:
> 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.

An approach that sometimes works is to develop a VCS-based outline
(based on the comments above and Brian's earlier comments) to which
folks can contribute details.  If attribution for contributions is
made and maintained, this can result in anything from resume-builder
to leadership development, particularly for junior folks.  If someone
on the development team could take a little time to suggest authors
based on previous email replies or perceived expertise, perhaps
something useful, even if not complete, could be pounded out.  If it
doesn't develop fully, the pieces that do can still be used in a
FAQ-like format.

Sean

> _______________________________________________
> Gluster-users mailing list
> Gluster-users at gluster.org
> http://supercolony.gluster.org/mailman/listinfo/gluster-users