Uploaded image for project: 'Accumulo'
  1. Accumulo
  2. ACCUMULO-4630

Move user manual to Accumulo website

VotersWatch issueWatchers
    XMLWordPrintableJSON

    Details

    • Type: Improvement
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 2.0.0
    • Fix Version/s: 2.0.0
    • Component/s: docs
    • Labels:
      None

      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

            Activity

              People

              • Assignee:
                mikewalch Mike Walch
                Reporter:
                mikewalch Mike Walch

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Time Tracking

                  Estimated:
                  Original Estimate - Not Specified
                  Not Specified
                  Remaining:
                  Remaining Estimate - 0h
                  0h
                  Logged:
                  Time Spent - 1h 40m
                  1h 40m

                    Issue deployment