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

[Kathy Lussier]

Sorry! I had intended to send this to the DIG list as well.

Kathy
 
 

>>-----Original Message-----
>>From: open-ils-general-bounces at list.georgialibraries.org [mailto:open-
>>ils-general-bounces at list.georgialibraries.org] On Behalf Of Kathy
>>Lussier
>>Sent: Tuesday, December 06, 2011 4:05 PM
>>To: open-ils-general at list.georgialibraries.org
>>Subject: Re: [OPEN-ILS-GENERAL] [OPEN-ILS-DOCUMENTATION] Documentation
>>Interest Group Meeting: Today, December 5
>>
>>Hi Robert,
>>
>>Thanks for posting this message. I put my name next to sections for
>>which I already have some 2.1 docs that I just need to review to make
>>sure I remove anything specific to local policies. I will try to
>>complete that review by the end of next week.
>>
>>I also added some sections to the cataloging outline, with links to
>>ESI documentation, for some of the cataloging development sponsored by
>>MassLNC. Since there is now a unified volume/copy editor, I thought it
>>might be necessary to now offer two sets of docs for adding holdings
>>since some libraries may continue to use the traditional volume and
>>copy creator while others may move to the unified one. Does this make
>>sense?
>>
>>Thanks!
>>Kathy
>>
>>Quoting "Soulliere, Robert" <robert.soulliere at mohawkcollege.ca>:
>>
>>> 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/relno
>>tes_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.
>>>
>>