accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Walch <mwa...@apache.org>
Subject Re: [DISCUSS] Move user manual source to Accumulo website repo
Date Wed, 26 Apr 2017 13:43:54 GMT
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.

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.

On Tue, Apr 25, 2017 at 5:19 PM Josh Elser <josh.elser@gmail.com> wrote:

> 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message