[OPEN-ILS-DOCUMENTATION] ***SPAM*** RE: Release Notes in the Docs
June Caola-Stokoe
jstokoe at cwmars.org
Wed Nov 20 11:33:10 EST 2013
I need to change my subscription to get the individual emails. At this moment, I only get the digest so this may be a little after the fact. Three comments:
1-Because Evergreen is open source, the software development process (including documentation) doesn't go through the traditional process. Traditionally, technical writers would collaborate with engineers to create documentation as development is in process. The practice creates a good dialog where the writer prods the engineer with questions that may not appear obvious to the developer. That said, I'm wondering if it would be worthwhile to pair a member of DIG with a developer when significant development is being done, or perhaps assign a DIG person to various components of a release...
2-Having attended the DIG Hackfest on Friday, does changing the levels affect the process of bringing the documentation up to date once and for all? I'm not sure. I thought I'd throw it out because it may make sense to wait until that's completed first.
3-All the levels in the documentation table of contents makes it difficult to find what you're looking for. I was poking around to see if there's some kind of add-in that could make the toc collapsible. Thought I'd throw that out to see if anyone is aware of something.
That's it!
-----Original Message-----
From: open-ils-documentation-bounces at list.georgialibraries.org [mailto:open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of open-ils-documentation-request at list.georgialibraries.org
Sent: Wednesday, November 20, 2013 11:07 AM
To: open-ils-documentation at list.georgialibraries.org
Subject: OPEN-ILS-DOCUMENTATION Digest, Vol 67, Issue 13
Send OPEN-ILS-DOCUMENTATION mailing list submissions to
open-ils-documentation at list.georgialibraries.org
To subscribe or unsubscribe via the World Wide Web, visit
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
or, via email, send a message with subject or body 'help' to
open-ils-documentation-request at list.georgialibraries.org
You can reach the person managing the list at
open-ils-documentation-owner at list.georgialibraries.org
When replying, please edit your Subject line so it is more specific than "Re: Contents of OPEN-ILS-DOCUMENTATION digest..."
Today's Topics:
1. Re: Release Notes in the Docs (James Keenan)
2. Docs I'm working on (Remington Steed)
3. Re: Ideas for Docs Website (Lynn Floyd)
----------------------------------------------------------------------
Message: 1
Date: Wed, 20 Nov 2013 13:02:51 +0000
From: James Keenan <jkeenan at cwmars.org>
Subject: Re: [OPEN-ILS-DOCUMENTATION] Release Notes in the Docs
To: 'Documentation discussion for Evergreen software'
<open-ils-documentation at list.georgialibraries.org>
Message-ID:
<451C9629DD8C8F43B6A1AB55C3F7CC8F09D7F9D7 at exchange.cwmars.internal>
Content-Type: text/plain; charset="us-ascii"
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-0001.htm>
------------------------------
Message: 2
Date: Wed, 20 Nov 2013 15:51:43 +0000
From: Remington Steed <rjs7 at calvin.edu>
Subject: [OPEN-ILS-DOCUMENTATION] Docs I'm working on
To: Documentation discussion for Evergreen software
<open-ils-documentation at list.georgialibraries.org>
Message-ID:
<7738587620e34423b448c51c5360124f at BLUPR06MB227.namprd06.prod.outlook.com>
Content-Type: text/plain; charset="us-ascii"
Hi DIG,
I wanted to remind everyone to update the wiki whenever you are working on a specific doc assignment. I think this is especially helpful for things like adding in missing sections from older docs. In fact, I think we should add the missing sections to the "2.5 Documentation Needs" wiki page so people can claim them. For now, I've started a section at the bottom called "Old/Missing Sections Needing Review".
http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:2.5_needs
--
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/319740c0/attachment-0001.htm>
------------------------------
Message: 3
Date: Wed, 20 Nov 2013 10:31:15 -0500
From: "Lynn Floyd" <lfloyd at andersonlibrary.org>
Subject: Re: [OPEN-ILS-DOCUMENTATION] Ideas for Docs Website
To: "'Documentation discussion for Evergreen software'"
<open-ils-documentation at list.georgialibraries.org>
Message-ID: <00fd01cee605$8d4000d0$a7c00270$@andersonlibrary.org>
Content-Type: text/plain; charset="us-ascii"
+1 for both.
Lynn Floyd
<mailto:lfloyd at andersonlibrary.org> lfloyd at andersonlibrary.org Anderson County Library
864-260-4500 x181
<http://www.andersonlibrary.org/> http://www.andersonlibrary.org
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:10 PM
To: Documentation discussion for Evergreen software
Subject: [OPEN-ILS-DOCUMENTATION] Ideas for Docs Website
Hi DIG,
I have been thinking about a few ideas that could improve the Docs website and make the Docs easier to use. I would imagine both of these things being integrated into every page of the generated HTML docs, and I don't know how difficult that would be.
1. It seems the Docs website needs a search box. Could we try adding
something like a Google custom search engine (https://www.google.com/cse/)?
2. I think the Docs website needs an email link that lets readers
easily provide feedback about missing sections or other problems. Ideally, this link would be visible everywhere, so whenever someone is reading and finds a problem, the link is visible already. But it would be fine to try it in a prominent place near the top, and also in the footer.
Thoughts?
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/429a7e60/attachment.htm>
------------------------------
_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
End of OPEN-ILS-DOCUMENTATION Digest, Vol 67, Issue 13
******************************************************
More information about the OPEN-ILS-DOCUMENTATION
mailing list