Hi Remington!
Thanks for bringing this topic up. While working on the 2.5 release
notes, I also was thinking we either needed a template or maybe even
release-note-writing tips for developers to consult when writing the
notes. I've had a few ideas swirling around in my head that I'll mention
below.
Kathy Lussier
Project Coordinator
Massachusetts Library Network Cooperative
(508) 343-0128
[email protected]
Twitter: http://www.twitter.com/kmlussier
On 11/19/2013 5:02 PM, Remington Steed wrote:
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?
I could be off in my thinking on this, but I'm seeing that we have two
places where we put Release Notes. There's this page
http://evergreen-ils.org/documentation/release/RELEASE_NOTES_2_5.html to
which we link from the downloads page. And then there are the release
notes included in the official docs http://docs.evergreen-ils.org/2.5/.
We had to do some re-organizing of the release notes to only include two
levels (I think) so that it would fit on the
http://evergreen-ils.org/documentation/release/RELEASE_NOTES_2_5.html
version of the notes. The first level heading is for "Evergreen 2.5
Release Notes", the second level is for Upgrade Notes or New Features.
The third level is for the functional area. That just leaves two levels
on this page for the actual release notes entry.
Moving up that page in the official docs let's us add another level for
the http://docs.evergreen-ils.org/2.5/ version of the notes, but I don't
think it will help us with the other version. However, I think it would
be very nice to allow people to use three levels of headings, because,
in some cases, it was difficult to reorganize some of the content to
make it fit in this last release. Maybe there's another way to clearly
identify upgrade notes versus new features so that the additional level
isn't needed there?
<http://docs.evergreen-ils.org/2.5/>
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.
I actually prefer more detailed release notes that probably go a step
beyond a short summary without crossing the line into full
documentation. In some cases, a short summary is all that is required.
But, at a minimum, I would also love to see the following items clearly
identified in release note entries when applicable:
* Any new permissions that were added with the new feature.
* Any library settings, local/server admin settings, or other
configuration options (e.g. a new setting in config.tt2 for a new tpac
feature) that were added with the new feature. For example, if you look
at the release note entry for long overdue processing
http://docs.evergreen-ils.org/dev/_circulation_2.html#_long_overdue_circulations_management_2,
it is quite long, but that's because there were many new admin options
added with long overdue processing. They identify all new permissions,
all new action/triggers, all new billing types, and a new copy status.
By including this type of information in the release notes, a site that
is starting to plan for an upgrade not only sees what new features are
on their way, but can get a one page look at any permissions, settings,
or configurations that need to be looked at before upgrading.
Perhaps we can say that every release notes entry should start with a
summary, but should also include the above information below the
summary. If you have a nice summary at the beginning, it makes it easier
to cut off the release notes entry if it's needed and perhaps relocate
it in the official docs. I know there were two cases where I moved
release note entries into the official docs, and, in both cases, there
was nice summary at the beginning that made it easy to decide where to cut.
<http://docs.evergreen-ils.org/dev/_circulation_2.html#_long_overdue_circulations_management_2>
-When appropriate, DIG members will aim to incorporate Release Notes
into the main documentation before that version of Evergreen is released.
Would this be DIG members or the developers? Current practice is for the
developers to add release notes when they submit the code, though it
doesn't always happen. For the 2.4 release, this was done for the
majority of new features, and I only needed to add release note entries
for a few that had slipped through. In this last release, I found there
were more new features missing a release notes entry. In several cases,
the code had been originally submitted long enough ago that it actually
pre-dated the requirement for release note entries. Anyway, I have also
made a mental note to keep a closer watch on the Launchpad bugs as they
are submitted to make sure they have the notes and to add comments to
the bug report (or use the needsreleasenotes tag) when they are missing.
-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.)
I'm not sure if this would be part of the template or a general tips
document, but here are some ideas that I came up with as I was working
on the 2.5 release notes.
* As I mentioned above, release notes entries should include any new
permissions, new library settings, local/server admin settings or other
configuration options.
* This probably falls under the category of style guidelines. I think we
should be recommending that language used in release notes entries match
the language that is used either in the client (for staff function
changes) or in the catalog (for catalog changes). I think this makes the
release notes more accessible to the end user or to the new Evergreen
site that isn't yet entirely familiar with the lingo. As an example, the
word "Vandelay" is not used anywhere in the MARC Batch Import interface,
so we should try to use the term "MARC Batch Import". Another common one
is the use of org unit, organizational unit, or simply OU. Org unit
settings are called Library Settings in the client, so we should
probably call them Library Settings in the Release Notes.
* For the same reasons cited above, I think a good guideline for
identifying a new database setting when there is a corresponding staff
client interface is in the following format:
Staff Client Label (database name)
As an example from the current release notes:
New Library Settings:
* Vandelay Generate Default Barcodes (vandelay.item.barcode.auto)
* Vandelay Default Barcode Prefix (vandelay.item.barcode.prefix)
* Vandelay General Default Call Numbers (vandelay.item.call_number.auto)
* Vandelay Default Call Number Prefix (vandelay.item.call_number.prefix)
* Vandelay Default Copy Location (vandelay.item.copy_location.default)
* Vandelay Default Circulation Modifier
(vandelay.item.circ_modifier.default)
By following this format, users who will be updating a setting in the
client and those who will be making updates in the database will each
get the information they need.
Thanks for starting the discussion Remington!
Kathy
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
_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
[email protected]
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
