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 [email protected]<mailto:[email protected]> 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: [email protected] [mailto:[email protected]] 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/
_______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
