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 Tue, 25 Apr 2017 21:19:11 GMT
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
>>>
>

Mime
View raw message