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

[Kathy Lussier]

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
klussier at masslnc.org
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
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20131120/331048b2/attachment-0001.htm>