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 > > >
