accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Josh Elser <>
Subject Re: [DISCUSS] Move user manual source to Accumulo website repo
Date Wed, 26 Apr 2017 14:51:37 GMT
Thanks, Mike. I this helped solidify some of the confusion over the 
ambiguity of how this would work as a developer that I had.

Mike Walch wrote:
> I was thinking that each minor release (2.0, 2.1, etc) would have its own
> copy of the user manual markdown files in the master branch of the
> accumulo-website repo.  We actually do this now in that a user manual html
> file exists in master for each minor release. Currently, if you need to
> update documentation for 1.6, 1.7&  1.8, you need to update each minor
> release branch of Accumulo (I understand merging makes this easy), generate
> 3 user manual html files, check them into master branch of
> accumulo-website. Developers simplify it by not immediately pushing user
> manual changes to the website and waiting for the next bug fix release
> which could be several months away.

Is faster doc-deployment also a goal of this change? I'd agree that 
we've been relatively "lazy" in making changes like you point out; but, 
that's probably also in part trying to avoid the premature docs 
publishing you mention below.

Aside: HBase has recently automated their workflow so that when a change 
to their "user manual" is committed, Jenkins will automatically 
build+publish the generated HTML to their website. That might be 
something we could consider looking at for either our current workflow 
or this new workflow you're proposing. This hinged on some stuff from 
infra (ability to commit changes safely from ASF jenkins), but I believe 
this is all worked out now.

> One potential issue that I do see with moving user manual source to the
> accumulo-website repo is that if you make a code change to the 2.0 branch
> for an upcoming 2.0.3 bug fix release, you might not want the 2.0
> documentation updated for that change until 2.0.3 is released.  Developers
> will need to delay changing user manual until after release or add "since
> 2.0.3" to the new text in the user manual.  However, new features should
> not added in bugfix releases so I don't think this will be as common as
> correcting bad documentation which needs to go out right of way.

That's a good edge-case that we'll want/need to keep in mind.

Since you've thought about this (at least more than I have), might you 
be able to outline the high-level steps for our common docs cases in 
this "new world" you're proposing? I think our doc additions typically 
fall into the following buckets: new features, grammar/syntax fixes, 
FAQ/HOWTO for common administrative actions in production. e.g. a new 
feature would only land in one manual, whereas grammar/syntax would 
(likely) land in all. I'm wondering if we can compose a simple workflow. 
I also understand if you haven't thought that far ahead yet.

View raw message