Mailing-List: contact dev-help@accumulo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@accumulo.apache.org
Message-ID: <58FFBD4F.9040703@gmail.com>
Date: Tue, 25 Apr 2017 17:19:11 -0400
From: Josh Elser <josh.elser@gmail.com>
User-Agent: Postbox 3.0.11 (Macintosh/20140602)
MIME-Version: 1.0
To: dev@accumulo.apache.org
Subject: Re: [DISCUSS] Move user manual source to Accumulo website repo
References: <CAL4xCs=JZhjnEQT=HTRbHhbmeBXHnA1M3-JeBAuf+vB0BmjWAA@mail.gmail.com> <58FFAA2A.4060809@gmail.com> <CAL4xCs=g79NUtZfSqp_ksFkCE9RWtHoRvN6xYjZTz8XE=XN=LQ@mail.gmail.com>
In-Reply-To: <CAL4xCs=g79NUtZfSqp_ksFkCE9RWtHoRvN6xYjZTz8XE=XN=LQ@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
archived-at: Tue, 25 Apr 2017 21:19:29 -0000

I can respect the desire to separate technical documentation from 
examples. However, I think using a single branch of a repository to 
track the technical documentation is going to induce a larger burden on us.

When I make a commit to 1.7 to change the user manual, I most of the 
time would just merge that commit through to 1.8/2.0 as it generally 
applies to all branches. Conversely, if a change only applies to 
specific versions, I can easily no-op merge the commit through to other 
branches (or avoid certain branches via cherry-pick).

My understanding is that we would have a single branch of the website. 
How would we handle multiple versions of documentation via a single 
branch? Would `master` of accumulo-website include $x copies of the 
user-manual?

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.
>
> 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
>>>
>