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

[Lynn Floyd]

+1

 

Lynn Floyd 
 <mailto:lfloyd at andersonlibrary.org> lfloyd at andersonlibrary.org 
Anderson County Library 
864-260-4500 x181 
 <http://www.andersonlibrary.org/> http://www.andersonlibrary.org 
  

 

From: open-ils-documentation-bounces at list.georgialibraries.org
[mailto:open-ils-documentation-bounces at list.georgialibraries.org] On Behalf
Of Remington Steed
Sent: Tuesday, November 19, 2013 5:02 PM
To: Documentation discussion for Evergreen software
Subject: [OPEN-ILS-DOCUMENTATION] Release Notes in the Docs

 

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/20131120/9762bd43/attachment.htm>