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

[James Keenan]

I think it's a great idea to have a release notes process that is fairly well accepted by the community both for how those notes are generated and how they're integrated. If we can articulate this clearly and get feedback from developers on it, I think it might work out well.

I'll have to take a look at the current template later today before giving any thoughts on expanding that.

Jim

Jim Keenan
Library Applications Supervisor
jkeenan at cwmars.org<mailto:jkeenan at cwmars.org>
508-755-3323 x23

C/W MARS
67 Millbrook St., Suite 201
Worcester, MA 01606

P   Save a tree! Please don't print this e-mail unless it's really necessary.
Currently reading Mistress Bradstreet by Charlotte Gordon

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/7177ee78/attachment.htm>