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.
