accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher <ctubb...@apache.org>
Subject Re: [DISCUSS] Move user manual source to Accumulo website repo
Date Wed, 26 Apr 2017 02:46:44 GMT
On Tue, Apr 25, 2017 at 4:43 PM Mike Walch <mwalch@apache.org> wrote:

> This change is also part of a larger plan of mine to refactor the
> documentation.  After the user manual is moved to the website, I would like
> to refactor it and make it simpler.  In the future, I would like to see
> Accumulo documentation split between the user manual and the blog.
>
> User manual
> * Simple, easy to read documentation
> * Constantly reviewed for accuracy.
> * Must be changed to reflect any changes to Accumulo.
>
> Accumulo blog
> * Detailed posts about new features, designs, testing, applications
> * Accurate at the time the post was published.
> * Doesn't need to be reviewed after initial post or changed if Accumulo
> changes.
>
> The user manual and blog could complement each other.  If you create a new
> feature, you should add a simple overview and instructions on how to use it
> to the user manual.  A blog post could be written to announce the feature
> and describe the underlying motivation, design & implementation. The new
> section in the user manual and the blog post could link to each other.
>
>
I like most of this idea. I think our current user manual is far too wordy,
and the important technical bits are buried in explanations, examples, and
user stories, all of which can distract from the main points. Some of the
structural and density issues could be improved without the split, but I
think a split is better, because it gives us an opportunity to really
engage with the story-telling about how Accumulo features can be used
without worrying about disrupting or trying to fit into the rigid structure
of the technical docs that make it easy to navigate and useful.

For example: the user manual could say "a context class path provides
classloader isolation for a table's configured iterators; to use it, set X
property on your table", while one or more blog posts supplement this with
information like "this is how the context class path feature can be used to
do A/B testing... it might also be useful for these other things...".

The only nit I would have in what you described is that I think the links
should be one way: from the blogs to the manual. I think this improves
quality of our docs and eases navigation. A basic "see website for
examples" is probably fine, but "see Christopher Tubbs' for an explanation
on how to do X" is probably an indication that either 1) we could do a
better job in our inline explanation, or 2) what we are trying to explain,
or at least to the extent we are trying to explain it, is probably out of
scope.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message