accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Josh Elser <josh.el...@gmail.com>
Subject Re: [DISCUSS] Move user manual source to Accumulo website repo
Date Wed, 26 Apr 2017 14:58:11 GMT

Mike Walch 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'm thinking about how I would apply the above to a new feature 
(re-using data-center replication in my head...), and I'm a little lost 
as to the type of content that I'd include in the user manual and what 
I'd leave for the blog.

* Problem statement -- Blog
* Architecture/design -- Blog
* Shell commands/Java API -- user manual
* Example workflow - Blog (and user manual?)
* Important notes/details - ??

As a user, I'm used to referring to a user manual to get understanding 
on the high level implementation of a feature, the API I use to access 
the feature, a simple example to confirm that I read the API correctly, 
and any "gotchas" I need to know about.

A blog post is inherently nicer to read in passing, but I would find it 
frustrating if, when using the feature, I have to jump between two 
places to get necessary information.

Mime
View raw message