[OPEN-ILS-DOCUMENTATION] Documentation Interest Group Meeting: Today, December 5

[Yamil Suarez]

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 <dan at coffeecode.net> 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
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20111205/7a1070eb/attachment-0001.htm>