[OPEN-ILS-DOCUMENTATION] Release Notes in the Docs

[Remington Steed]

Hi DIG,

I'd like your feedback on a change I made.  After fixing a few docs bugs, I moved the Release Notes section up in the hierarchy, making it a main section (see the TOC<http://docs.evergreen-ils.org/dev/> for details).  AsciiDoc only has five levels of section indenting, so the sixth level is lost during processing.  We had a few "sixth level" subsections because the Release Notes actually started at Level 2 and used Level 3 for subdivisions ("Upgrade Notes" and "New Features"), which only leaves two more levels for authors to use.  Moving the Release Notes up a level solves this problem, and gives Release Notes authors an extra heading level to work with.  Is anyone opposed to this change?  Are there consequences I haven't thought of?

Also, I think we should define a little more clearly what we want from the developers when they submit release notes for their features.  This came up because some developers have provided more detailed release notes, which is wonderful!  However, it raises the question: How are release notes different from the other documentation?  Here is my first draft of how I think this process should work.  Please reply with your thoughts.


-          Release Notes are usually a short summary of changes and new features in a given version of Evergreen.

-          When appropriate, DIG members will aim to incorporate Release Notes into the main documentation before that version of Evergreen is released.

-          If a developer provides more detailed documentation as their release notes, they or someone else should provide a summary version to be used in the Release Notes section, and the longer version will be added to the main documentation.

-          DIG will provide a Release Notes Template that shows the best format for contributing Release Notes (including available heading levels).  (A template already exists at RELEASE_NOTES_NEXT/RELEASE_NOTE_TEMPLATE, so this could be expanded.)

Remington

--
Remington Steed
Electronic Resources Specialist
Hekman Library, Calvin College
http://library.calvin.edu/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20131119/502101c1/attachment.htm>