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

[Kathy Lussier]

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/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.
>