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: [email protected] [mailto:[email protected]] On Behalf Of [email protected] Sent: Wednesday, November 20, 2013 11:07 AM To: [email protected] Subject: OPEN-ILS-DOCUMENTATION Digest, Vol 67, Issue 13 Send OPEN-ILS-DOCUMENTATION mailing list submissions to [email protected] 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 [email protected] You can reach the person managing the list at [email protected] 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 <[email protected]> Subject: Re: [OPEN-ILS-DOCUMENTATION] Release Notes in the Docs To: 'Documentation discussion for Evergreen software' <[email protected]> Message-ID: <451C9629DD8C8F43B6A1AB55C3F7CC8F09D7F9D7@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 [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/ -------------- 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 <[email protected]> Subject: [OPEN-ILS-DOCUMENTATION] Docs I'm working on To: Documentation discussion for Evergreen software <[email protected]> Message-ID: <7738587620e34423b448c51c53601...@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" <[email protected]> Subject: Re: [OPEN-ILS-DOCUMENTATION] Ideas for Docs Website To: "'Documentation discussion for Evergreen software'" <[email protected]> Message-ID: <[email protected]> Content-Type: text/plain; charset="us-ascii" +1 for both. Lynn Floyd <mailto:[email protected]> [email protected] Anderson County Library 864-260-4500 x181 <http://www.andersonlibrary.org/> http://www.andersonlibrary.org From: [email protected] [mailto:[email protected]] 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 [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation End of OPEN-ILS-DOCUMENTATION Digest, Vol 67, Issue 13 ****************************************************** _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
