On Mon, Dec 05, 2011 at 09:11:23AM -0500, Karen Collier wrote: > The Evergreen Documentation Interest Group has its next meeting > scheduled for Monday December 5, 2011 (today) at 2:30 PM EST on the > #Evergreen IRC channel (http://evergreen-ils.org/irc.php). Anyone > interested in documentation is welcome to attend. An agenda has been > posted at > http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:dig_meetings > but changes and additions to the agenda are welcome.
I thought I would bring forward some interesting points from the rather spirited Community meeting we had on Friday, Dec. 2nd (minutes aren't up yet at http://evergreen-ils.org/dokuwiki/doku.php?id=community:meetings:2011-12-02 but the raw IRC log is at http://evergreen-ils.org/irc_logs/evergreen/2011-12/%23evergreen.02-Fri-2011.log ) * The topic of the draft community support policy for Evergreen releases (two concurrent release series, plus one month of support for a third release series after the GA of the newest release series) elicited a fairly strong response, with concerns expressed about stability and timing of the releases, but of particular interest to the DIG, about the problem of having major releases without release notes or accompanying documentation. See 2011-12-02T14:56:42 for the beginning of the discussion. One suggestion for trying to address the lack of release notes at release time included writing commit messages that are much more verbose; possibly to the point of automatically generating a rough draft of release notes from commit messages. I think the development team has improved the quality of its commit messages in general over the past year, but I can certainly bring that message back to the development team at tomorrow's dev meeting if members of the DIG have found that useful / want more. I used the commit logs as the starting point for the Release Notes for 2.1.0 that others thankfully chipped into at http://evergreen-ils.org/documentation/release/ - certainly having more than a bullet point for a given feature is necessary to successfully use a new feature, but hopefully these can serve as a platform for fleshing out the 2.1 documentation (or at least creating placeholders for "more info needed here!" - heh). On the release notes - I'm hoping to begin keeping the release notes in the Evergreen source tree in AsciiDoc form, such that when a developer commits a new features or introduces compatibility changes, the dev can add a section to the release notes at the same time. I've pushed a branch at http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/dbs/relnotes_22 with that thought in mind. A bit too late to capture everything for 2.2, probably, but it can be a start, at least. On the current lack of official documentation for 2.1 features, there is a recognition that the DIG is doing what it can with the volunteers and time that they have. I did suggested that "not making the DIG jump through licensing hurdles would probably help get some 2.1 docs in place" and Jason Etheridge said he would "poke folks into providing something unambigious and easily referenceable" with respect to "granting a CC-BY-SA license that applies to all versions of Equinox docs that appear in some specific location". Aside: the normal DIG contribution process at http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:how-to-contribute-documentation could mention the CC-BY-SA license up front to help avoid misunderstandings. In general, I think there was a feeling that we need people who can have a foot in both worlds of development and documentation to help smooth things along. On AsciiDoc - given that we're now keeping install instructions in the Evergreen source tree in AsciiDoc form, as well as working towards release notes in the Evergreen source tree in AsciiDoc form, and the ESI docs also come in AsciiDoc form, would it be a crazy idea to consider trying out an all-AsciiDoc manual for a future release - say, 2.2? On the bright side, basic HTML output from AsciiDoc is easy to set up on Windows, so it should present a lower barrier for Windows-based people who just want a basic test for the formatting of their docs. However, PDF or other formats still require you to set up the full DocBook processing chain. (It's a snap to set up on Linux, naturally!) Apologies for the long missive, but I thought it would be important to draw attention to some of the points raised in the Community Meeting (even with my own particular bias). I think a positive takeaway is that people have grown to expect the kind of coverage that the DIG provided with the 1.6 manual and want that and more for 2.1 and beyond! _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list OPEN-ILS-DOCUMENTATION@list.georgialibraries.org http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation