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<[email protected]> 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
