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.
