Sorry! I had intended to send this to the DIG list as well. Kathy
>>-----Original Message----- >>From: [email protected] [mailto:open- >>[email protected]] On Behalf Of Kathy >>Lussier >>Sent: Tuesday, December 06, 2011 4:05 PM >>To: [email protected] >>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" <[email protected]>: >> >>> 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 >>> [email protected] >>> Telephone: 905 575 1212 x3936 >>> Fax: 905 575 2011 >>> ________________________________________ >>> From: [email protected] >>> [[email protected]] On Behalf >>> Of Dan Scott [[email protected]] >>> 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 >>> [email protected] >>> 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. >>> >> _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
