accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Walch <mwa...@apache.org>
Subject Re: [DISCUSS] Move user manual source to Accumulo website repo
Date Tue, 25 Apr 2017 20:43:21 GMT
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.

On Tue, Apr 25, 2017 at 3:57 PM Josh Elser <josh.elser@gmail.com> wrote:

> copy-pasting from the JIRA issue because I was looking for these in-thread:
>
> <snip>
> Pros
> * Easier to link between pages and external Javadocs
> * Documentation can be broken up into distinct pages which is easier to
> read and better for SEO.
> * Easier to update documentation after releases. Only one commit necessary.
> * Jekyll+Markdown is more customizable and becoming more of a standard
> than asciidoc.
> * Documentation changes that affect multiple releases can be made with
> one PR.
>
> Cons
> * Documentation will no longer ship with tarball
> * Developers cannot update code and docs in one PR
> </snip>
>
> Mike Walch wrote:
> > For 2.0, I would like convert user manual source from asciidoc to
> markdown
> > and move it to the accumulo-website to be served using Jekyll.  While I
> > will put these changes up for review, I would like to see if anyone has
> any
> > major objections or suggestions before I start work on it (I do not want
> to
> > spend a lot of time doing a tedious conversion if someone is going to -1
> > the change). Below is the issue if you want to comment in JIRA:
> >
> > https://issues.apache.org/jira/browse/ACCUMULO-4630
> >
>

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