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.
