Dan, Thank you very much for the recap of the DIG related discussions that occurred at the last EG community meeting. I just got a chance last night to read over the logs, and I am glad that you have gotten already got the rest of DIG informed before our afternoon meeting.
With what I have seen of ASCIIDoc, I definitely see why its simple syntax is so appealing. My early thought is that at this point I think that getting rough documentation in ASCIIDoc from developers (or non-developers) would be really great, even if we still have to do automatic conversion to DocBook to match our current DIG set up. I am glad to report that both Robert Soulliere I have done some testing with converting from ASCIIDoc to DocBook. At this very early junction, my initial results have been promising, though only for converting the README file. I suspect Robert might has had similar results. Switching to an all ASCIIDoc workflow at some point in the future could make sense specially if we get a lot of ASCIIDoc documentation, but I am not sure when it would be the time to make that decision. Thanks again, Yamil On Mon, Dec 5, 2011 at 10:15 AM, Dan Scott <[email protected]> wrote: > 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 > [email protected] > http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation >
_______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
