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

Tue Dec 6 09:34:42 EST 2011

Hi All,

Just to follow up on some things that came out of yesterday's DIG meeting and make a request to help get documentation existing in the wild into the official documentation.

The 2.1 DocBook documentation is now set up to be processed nightly. The link to 2.1 is now available at http://docs.evergreen-ils.org/

The installation chapter was converted from the README asciidoc file found in the code. -- hopefully folks could try out these steps and see if it is relatively reasonable to follow for new users.

The Upgrade instructions are a combination of the install steps for getting Evergreen from 2.0.x to 2.1.1:
http://open-ils.org/dokuwiki/doku.php?id=upgrading:evergreen:2.1

The Release notes are from:
http://open-ils.org/documentation/release/RELEASE_NOTES_2_1_0.html

The documentation is extremely sparse... That is where you come in.;-)

I know some documentation exists and some documentation can be carried over from 2.0. Could folks use the outline at:
http://open-ils.org/dokuwiki/doku.php?id=evergreen-docs_2.1:outline
to indicate where documentation exists for the specific chapters? For example, indicate where the ESI docs might fit in. If I see it here, I will convert it to DocBook and get it into the 2.1 documentation.

-- If you know of existing documentation please add a link where we can get it.
-- If you think it can be brought over from 2.0 please indicate with "port from 2.0".
-- If you can work on a section please indicate that with your name and "assigned".
-- If you know of where documentation can be found in code notes or readmes within the code, please indicate that and the file/link to the repository location.

At the very least, this can be a guide for others to find existing documentation until the official docs can catch up.

As well, it might be good to review the 2.0 outline to indicate if there is documentation to fill in some of the 2.0 gaps.
http://open-ils.org/dokuwiki/doku.php?id=evergreen-docs_2.0:outline

If you are unable to edit that wiki page and do not want to request a login to edit that wiki page, please send a link or documentation you wish to share to the DIG list or one of the content coordinators or me to get it included and we will edit that page.

In regards to ideas about how the release team can coordinate with the DIG to get official documentation released when software is released, how about these:

1) Establish a list of the required base documentation needed at release time for any release of Evergreen. I am thinking the chapter on Installation, upgrades and Release notes for sure. Please list others? Most of this is getting pre-written in asciidoc as mentioned by Dan, so it should not be difficult to get a base documentation at release time as long as we know where to get it.

2) Have someone in DIG on the official release team to ensure base documentation is completed on time. -- Someone at the DIG meeting mentioned that that was already established but am not aware of anyone in that official role at this time.

3) Documentation to cover brand new features or system changes as with booking modules in 1.6.1, EDI in 2.0, etc... However, this is tricky for me to promise because many new features are developed by vendors with various documentation agreements. I should note that a very valiant effort is being made by vendors to share documentation and the process is being improved to share new feature documentation with the community. The earlier this information is shared with the DIG, the more quickly it can get into the documentation. As a future example, getting template toolkit documentation would be essential at an early stage for 2.2 since this is a brand new major enhancement and the community needs to understand this for customizing OPACs.

4) A developer on the inside coordinating with DIG. I think this was suggested at the community meeting and DIG meeting. I also think this is important to coordinate effort and also think that there are chapters in the documentation which mush be written by developers. Of course, developer free time is premium and limited so I understand the challenges.

5) More questions on the DIG list.

6) Documentation prioritizing?On top of the base essential list of mandatory chapters to be released, perhaps we can come up with a priority list of missing documentation which needs to be tackled? Or we could add an "high priority" indicator to the outline ( http://open-ils.org/dokuwiki/doku.php?id=evergreen-docs_2.1:outline )   so that the DIG can make better decisions on focusing limited resources.

The main challenge for the DIG is that most of the volunteers are the users of Evergreen and not the developers. Writing the documentation requires testing and learning. Many of the DIG contributors are unable to work on the latest versions of Evergreen until after it is released so we are feeling around in the dark when it comes to the new features as other admins and staff users. I am afraid that is the nature of the volunteer DIG structure at this time. So in essence, timely documentation of new  features needs to come from the organizations, venders, developers, etc who sponsor or develop it. I do see great improvement in this area, but I think using the outline I mentioned earlier will get DIG find the existing documentation in whatever format it is written.

Regards,
Robert

Robert Soulliere, BA (Hons), MLIS
Systems Librarian
Mohawk College Library
robert.soulliere at mohawkcollege.ca
Telephone: 905 575 1212 x3936
Fax: 905 575 2011
________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Dan Scott [dan at coffeecode.net]
Sent: December 5, 2011 10:15 AM
To: Documentation discussion for Evergreen software
Cc: open-ils-dev; open-ils-general
Subject: Re: [OPEN-ILS-DOCUMENTATION] Documentation Interest Group Meeting: Today, December 5

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

This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.