Major Description
Current documentation - The Accumulo user manual lives in the Accumulo repo in an asciidoc format. After every release or doc change, a single page html file must be generated and copied to website.
Proposal - Convert all documentation (starting with 2.0) from asciidoc to markdown, move to Accumulo website and serve using Jekyll. Unreleased documentation will be published (with a warning) but not linked to. After a release, remove warning and add links. Wait a week or two for additional changes before copying all documentation to new directory for next release.
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
Attachments
Issue Links
- links to
