[OPEN-ILS-DOCUMENTATION] Quick note on release notes

[Remington Steed]

Hi Yamil,

Yes, it sounds like your idea is very similar to my proposal.  So I think you are right that DIG doesn't need to discuss it any further.

I actually had another question regarding release notes.  It seems that the developers want more direction about what to provide as release notes.  Some of them actually provide thorough documentation.  I think it would be helpful to put this on the agenda for the next Developer meeting, where DIG could propose a simple definition of "Release Notes" compared to "Normal Documentation".  And if developers want to write normal docs, we could give them a directory to put them in similar to the RELEASE_NOTES_NEXT directory.  We could call it DOCS_NEXT.

Here's my proposal for definitions of "Release Notes" and "Normal Documentation".  Everyone, please send your comments!

************
Release Notes
------------------
Every new feature (or otherwise significant change to Evergreen) should have a short description of what it does differently than before, and how to get it working.  I particular, it should list any new settings or permissions included with this feature, and any existing settings or permissions that are required to use the new feature. Also, if this feature influences the upgrade process (e.g. by adding required steps, increasing the ingest time, etc.), you should include this information in an "Upgrade Notes" section.  Otherwise, Release Notes should be kept short and should usually not include screenshots or step-by-step instructions.  Files can be added to the source directory "RELEASE_NOTES_NEXT" in the appropriate subdirectory.  Upgrade notes can be included in an "Upgrade Notes" section of your release notes or added as a separate file to an "upgrade" subdirectory within your appropriate subdirectory.

Normal Documentation
-----------------------------
This should contain everything an Evergreen user or administrator needs to know about the new feature (or otherwise significant change to Evergreen).  Screenshots and step-by-step instructions are generally very helpful.  Files can be added to the source directory "DOCS_NEXT".  If you know where this information would fit best in the existing Evergreen documentation, please mention that on the DIG email list or make an appropriately named subdirectory for your file.  

--
Remington Steed
Electronic Resources Specialist
Hekman Library, Calvin College
http://library.calvin.edu/

> -----Original Message-----
> From: open-ils-documentation-bounces at list.georgialibraries.org
> [mailto:open-ils-documentation-bounces at list.georgialibraries.org] On
> Behalf Of Yamil Suarez
> Sent: Tuesday, April 15, 2014 12:55 PM
> To: Documentation discussion for Evergreen software
> Subject: [OPEN-ILS-DOCUMENTATION] Quick note on release notes
> 
> Hola,
> 
> I wanted to give you a heads up of what I wanted to mention on the list
> about release notes, but I will not since it is really redundant now that I
> thought about it since your proposal essentially covered it already. So the
> topic I had  wanted to bring up is that there are a lot new features that are
> only mentioned briefly in the "new features" section of past docs. Then, at
> the DIG hackfest we started talking casually if we could get into the habit that
> ALL new features should appear both in the beginning of the official docs
> (like they are now), but also fleshed out or copied verbatim in a reasonable
> section of the manual. Which is pretty much what you proposed. Also, that
> we need to eventually go back to older versions and slowly move those
> features into the main sections of the manuals just like we are attempting to
> do with 2.6.
> 
> So there is really nothing I need to say anymore, since we covered this in the
> meeting, with the timeline of doing 2.6 first then going back if there is time.
> 
> Therefore I will not be sending any letters to the group about this after all,
> Yamil
> 
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation