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

[Dan Scott]

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!