Re: [OPEN-ILS-GENERAL] Documentation proposal -- input requested
That sounds like a session I'd like to attend. :) Karen C - Karen Schneider k...@esilibrary.com wrote: The conference idea (slaps forehead) that's inspired! That sounds like at least one program -- heck it could even be a Hackfest, a kind of gonzo instruction class involving installing a free open source XML editor, applying templates, working in XML, etc. (There's no reason Hackfests need to be limited to development!) thanks, Catherine! Thoughts from others in the community? Karen S. On Thu, Jan 29, 2009 at 2:38 PM, Catherine Buck Morgan cmor...@statelibrary.sc.gov wrote: Karen, I was reading this last night and checking out Docbook. To say this is a timely topic would be an understatement… I love the title, by the way—The Book of Evergreen. One thing that stood out particularly was the ability to translate the documentation to word and pdf. (I've decided I'm the tween generation… remember and appreciate the good old paper manual, like the convenience of online contextual documentation, but still want to be able to scribble my notes in the margins of how it really works for my system…. ) I really think you're on the right road with the XML platform. Using (or an intro to) Docbook might be a good topic for the conference… --Catherine. -- Catherine Buck Morgan Director, Division of Innovation, Technology Library Services South Carolina State Library POB 11469, 1500 Senate Street, Columbia, SC 29211 Phone: 803-734-8651 | Fax: 803-734-4757 cmor...@statelibrary.sc.gov www.statelibrary.sc.gov The South Carolina State Library is a national model for innovation, collaboration, leadership and effectiveness. It is the keystone in South Carolina's intellectual landscape. From: open-ils-general-boun...@list.georgialibraries.org [mailto: open-ils-general-boun...@list.georgialibraries.org ] On Behalf Of Karen Schneider Sent: Thursday, January 29, 2009 8:47 AM To: Evergreen Discussion Group; Evergreen Development Discussion List; Public Open-ILS documentation discussion Subject: [OPEN-ILS-GENERAL] Documentation proposal -- input requested Hi folks, two weeks back there were a flurry of posts about an Evergreen documentation project plan. I will plan a webinar for a conversation about this proposal, but if you have thoughts to share on or off the list, your input would be very welcome. Input could range from Yes, that's a good idea -- carry on to I suggest X about Y to This is the most ghastly proposal I have seen in my X years working in libraries. This is the proposal: http://docs.google.com/Doc?id=ddzqk523_264f2vk5vpn Note that there are any kind of top-level decisions to be made, with corollary activity that follows, and it's not even a given we call the documentation The Book of Evergreen (especially if it turns out to be in volumes...). That has been its working title, and in the absence of better ideas, etc. etc., but a discussion about the title would also be timely. Also, Betty Ing, a documentation intern at Project Conifer, has published a comparison of Style Guidelines for Fedora and Book of Evergreen. For those who missed her post (to the documentation list) I published her cross-walk here: http://spreadsheets.google.com/pub?key=pqvVF5hSEbDO6MlrXHXxDUg This crosswalk reinforces the suggestions in the proposal. We've seen some excellent documentation emerging from various parts of the Evergreen community, and channeling it into an intentional project integrated with larger Evergreen efforts would be excellent. -- -- | Karen G. Schneider | Community Librarian | Equinox Software Inc. The Evergreen Experts | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712 | E-Mail/AIM: k...@esilibrary.com | Web: http://www.esilibrary.com -- -- | Karen G. Schneider | Community Librarian | Equinox Software Inc. The Evergreen Experts | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712 | E-Mail/AIM: k...@esilibrary.com | Web: http://www.esilibrary.com -- Karen Collier Public Services Librarian Kent County Public Library 408 High Street Chestertown, MD 21620 410-778-3636
Re: [OPEN-ILS-GENERAL] Documentation proposal -- input requested
Some terrific ideas! I admit that I am really a noob myself in this arena and running as fast as I can to learn more... the idea of a documentation hackfest appeals in part because it forces some larnin'. ;) A two-part hackfest, even better. People who will help organize such an event -- priceless. (Looks around...) Concur on the model chapter idea, though would almost rather it be something that was about Evergreen, even a small topic. (For those of you who can remember back this far, think Fanny Farmer Junior Cookbook. Or for those who homebrew, think how the classic brewing texts walk you through a real recipe.) The idea of encouraging XML but not dampening the ardor of those for whom even a friendly XML editor is a barrier is a good one. I was asked yesterday if we really, really needed XML, or if we couldn't just get by on Dokuwiki and text-based documentation. I think Dan Scott made a great argument why this is not the case two years ago in his original proposal. A really strong XML structure tends to guide the style of the documentation as much as anything else. Also, the possibilities for translation, formatting, and reuse are much better if it's in XML. I would say, from looking around, that the majority of serious OSS projects use XML-based documentation. Also, and this won't seem odd to people who spend hands-on time with both, I think XML is actually easier to learn and create than wiki-based documentation -- even if you aren't using a GUI. Wiki syntax is highly bespoke and laborious; XML at least makes sense. Karen G. Schneider On Fri, Jan 30, 2009 at 11:11 AM, Duimovich, George george.duimov...@nrcan-rncan.gc.ca wrote: Agree - that would be a great idea. It would be nice, but not realistic to expect all contributed documentation to be submitted in DocBook format. Still, building some capacity and familiarity can only help move this forward. A little boost with the learning curve, and some focus on exposing core elements, practices, etc. would be of interest. We're wanting to see some core investment made into professional documentation (e.g. dedicated staff at ESI and with any large sponsored EG projects, etc.), but it would also be helpful for those whose organizations may from time to time contribute code, plug-ins, etc. that merit more than a snippet of documentation. I would suggest that if such a session takes place, that there be a model chapter and/or section (even just in Greek text if need be) that demonstrates the use of core elements of interest from the DocBook standard, and formatted according to whatever appropriate stylesheet, etc.. So how to express code, use communications devices like tips callouts, etc. in a 3-5 page document. And for the advanced, we could also go into to interact it with subversion, automation to multiple formats, etc. At the very least, once a model documentation sample is available (as Greek text or preferably a real sample), any group contributing code could then use it as kind of a template to follow, thereby bringing doc contributions up a notch in terms of quality, consistency etc. and the barrier to using DocBook down a notch. So for the conference, perhaps we could look to walk away from it with a few more eyes familiarized with a basic overview of documentation toolbox, and also a nice sample template to have available for those who may be able to make contributions. cheers, George Duimovich NRCan Library / Bibliothèque RNCan -- *From:* open-ils-general-boun...@list.georgialibraries.org [mailto: open-ils-general-boun...@list.georgialibraries.org] *On Behalf Of *Karen Schneider *Sent:* January 30, 2009 9:37 AM *To:* Evergreen Discussion Group *Subject:* Re: [OPEN-ILS-GENERAL] Documentation proposal -- input requested The conference idea (slaps forehead) that's inspired! That sounds like at least one program -- heck it could even be a Hackfest, a kind of gonzo instruction class involving installing a free open source XML editor, applying templates, working in XML, etc. (There's no reason Hackfests need to be limited to development!) thanks, Catherine! Thoughts from others in the community? Karen S. On Thu, Jan 29, 2009 at 2:38 PM, Catherine Buck Morgan cmor...@statelibrary.sc.gov wrote: Karen, I was reading this last night and checking out Docbook. To say this is a timely topic would be an understatement… I love the title, by the way—The Book of Evergreen. One thing that stood out particularly was the ability to translate the documentation to word and pdf. (I've decided I'm the tween generation… remember and appreciate the good old paper manual, like the convenience of online contextual documentation, but still want to be able to scribble my notes in the margins of how it really works for my system…. ) I really think you're on the right road with the XML platform. Using (or an intro to) Docbook might be a good topic
Re: [OPEN-ILS-GENERAL] Documentation proposal -- input requested
The conference idea (slaps forehead) that's inspired! That sounds like at least one program -- heck it could even be a Hackfest, a kind of gonzo instruction class involving installing a free open source XML editor, applying templates, working in XML, etc. (There's no reason Hackfests need to be limited to development!) thanks, Catherine! Thoughts from others in the community? Karen S. On Thu, Jan 29, 2009 at 2:38 PM, Catherine Buck Morgan cmor...@statelibrary.sc.gov wrote: Karen, I was reading this last night and checking out Docbook. To say this is a timely topic would be an understatement… I love the title, by the way—The Book of Evergreen. One thing that stood out particularly was the ability to translate the documentation to word and pdf. (I've decided I'm the tween generation… remember and appreciate the good old paper manual, like the convenience of online contextual documentation, but still want to be able to scribble my notes in the margins of how it really works for my system…. ) I really think you're on the right road with the XML platform. Using (or an intro to) Docbook might be a good topic for the conference… --Catherine. -- Catherine Buck Morgan Director, Division of Innovation, Technology Library Services South Carolina State Library POB 11469, 1500 Senate Street, Columbia, SC 29211 Phone: 803-734-8651 | Fax: 803-734-4757 cmor...@statelibrary.sc.gov www.statelibrary.sc.gov The South Carolina State Library is a national model for innovation, collaboration, leadership and effectiveness. It is the keystone in South Carolina's intellectual landscape. *From:* open-ils-general-boun...@list.georgialibraries.org [mailto: open-ils-general-boun...@list.georgialibraries.org] *On Behalf Of *Karen Schneider *Sent:* Thursday, January 29, 2009 8:47 AM *To:* Evergreen Discussion Group; Evergreen Development Discussion List; Public Open-ILS documentation discussion *Subject:* [OPEN-ILS-GENERAL] Documentation proposal -- input requested Hi folks, two weeks back there were a flurry of posts about an Evergreen documentation project plan. I will plan a webinar for a conversation about this proposal, but if you have thoughts to share on or off the list, your input would be very welcome. Input could range from Yes, that's a good idea -- carry on to I suggest X about Y to This is the most ghastly proposal I have seen in my X years working in libraries. This is the proposal: http://docs.google.com/Doc?id=ddzqk523_264f2vk5vpn Note that there are any kind of top-level decisions to be made, with corollary activity that follows, and it's not even a given we call the documentation The Book of Evergreen (especially if it turns out to be in volumes...). That has been its working title, and in the absence of better ideas, etc. etc., but a discussion about the title would also be timely. Also, Betty Ing, a documentation intern at Project Conifer, has published a comparison of Style Guidelines for Fedora and Book of Evergreen. For those who missed her post (to the documentation list) I published her cross-walk here: http://spreadsheets.google.com/pub?key=pqvVF5hSEbDO6MlrXHXxDUg This crosswalk reinforces the suggestions in the proposal. We've seen some excellent documentation emerging from various parts of the Evergreen community, and channeling it into an intentional project integrated with larger Evergreen efforts would be excellent. -- -- | Karen G. Schneider | Community Librarian | Equinox Software Inc. The Evergreen Experts | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712 | E-Mail/AIM: k...@esilibrary.com | Web: http://www.esilibrary.com -- -- | Karen G. Schneider | Community Librarian | Equinox Software Inc. The Evergreen Experts | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712 | E-Mail/AIM: k...@esilibrary.com | Web: http://www.esilibrary.com
Re: [OPEN-ILS-GENERAL] Documentation proposal -- input requested
Agree - that would be a great idea. It would be nice, but not realistic to expect all contributed documentation to be submitted in DocBook format. Still, building some capacity and familiarity can only help move this forward. A little boost with the learning curve, and some focus on exposing core elements, practices, etc. would be of interest. We're wanting to see some core investment made into professional documentation (e.g. dedicated staff at ESI and with any large sponsored EG projects, etc.), but it would also be helpful for those whose organizations may from time to time contribute code, plug-ins, etc. that merit more than a snippet of documentation. I would suggest that if such a session takes place, that there be a model chapter and/or section (even just in Greek text if need be) that demonstrates the use of core elements of interest from the DocBook standard, and formatted according to whatever appropriate stylesheet, etc.. So how to express code, use communications devices like tips callouts, etc. in a 3-5 page document. And for the advanced, we could also go into to interact it with subversion, automation to multiple formats, etc. At the very least, once a model documentation sample is available (as Greek text or preferably a real sample), any group contributing code could then use it as kind of a template to follow, thereby bringing doc contributions up a notch in terms of quality, consistency etc. and the barrier to using DocBook down a notch. So for the conference, perhaps we could look to walk away from it with a few more eyes familiarized with a basic overview of documentation toolbox, and also a nice sample template to have available for those who may be able to make contributions. cheers, George Duimovich NRCan Library / Bibliothèque RNCan From: open-ils-general-boun...@list.georgialibraries.org [mailto:open-ils-general-boun...@list.georgialibraries.org] On Behalf Of Karen Schneider Sent: January 30, 2009 9:37 AM To: Evergreen Discussion Group Subject: Re: [OPEN-ILS-GENERAL] Documentation proposal -- input requested The conference idea (slaps forehead) that's inspired! That sounds like at least one program -- heck it could even be a Hackfest, a kind of gonzo instruction class involving installing a free open source XML editor, applying templates, working in XML, etc. (There's no reason Hackfests need to be limited to development!) thanks, Catherine! Thoughts from others in the community? Karen S. On Thu, Jan 29, 2009 at 2:38 PM, Catherine Buck Morgan cmor...@statelibrary.sc.gov wrote: Karen, I was reading this last night and checking out Docbook. To say this is a timely topic would be an understatement... I love the title, by the way-The Book of Evergreen. One thing that stood out particularly was the ability to translate the documentation to word and pdf. (I've decided I'm the tween generation... remember and appreciate the good old paper manual, like the convenience of online contextual documentation, but still want to be able to scribble my notes in the margins of how it really works for my system ) I really think you're on the right road with the XML platform. Using (or an intro to) Docbook might be a good topic for the conference... --Catherine. -- Catherine Buck Morgan Director, Division of Innovation, Technology Library Services South Carolina State Library POB 11469, 1500 Senate Street, Columbia, SC 29211 Phone: 803-734-8651 | Fax: 803-734-4757 cmor...@statelibrary.sc.gov www.statelibrary.sc.gov The South Carolina State Library is a national model for innovation, collaboration, leadership and effectiveness. It is the keystone in South Carolina's intellectual landscape. From: open-ils-general-boun...@list.georgialibraries.org [mailto:open-ils-general-boun...@list.georgialibraries.org] On Behalf Of Karen Schneider Sent: Thursday, January 29, 2009 8:47 AM To: Evergreen Discussion Group; Evergreen Development Discussion List; Public Open-ILS documentation discussion Subject: [OPEN-ILS-GENERAL] Documentation proposal -- input requested Hi folks, two weeks back there were a flurry of posts about an Evergreen documentation project plan. I will plan a webinar for a conversation about this proposal, but if you have thoughts to share on or off the list, your input would be very welcome. Input could range from Yes, that's a good idea -- carry on to I suggest X about Y to This is the most ghastly proposal I have seen in my X years working in libraries. This is the proposal: http://docs.google.com/Doc?id=ddzqk523_264f2vk5vpn Note that there are any kind of top-level
[OPEN-ILS-GENERAL] Documentation proposal -- input requested
Hi folks, two weeks back there were a flurry of posts about an Evergreen documentation project plan. I will plan a webinar for a conversation about this proposal, but if you have thoughts to share on or off the list, your input would be very welcome. Input could range from Yes, that's a good idea -- carry on to I suggest X about Y to This is the most ghastly proposal I have seen in my X years working in libraries. This is the proposal: http://docs.google.com/Doc?id=ddzqk523_264f2vk5vpn Note that there are any kind of top-level decisions to be made, with corollary activity that follows, and it's not even a given we call the documentation The Book of Evergreen (especially if it turns out to be in volumes...). That has been its working title, and in the absence of better ideas, etc. etc., but a discussion about the title would also be timely. Also, Betty Ing, a documentation intern at Project Conifer, has published a comparison of Style Guidelines for Fedora and Book of Evergreen. For those who missed her post (to the documentation list) I published her cross-walk here: http://spreadsheets.google.com/pub?key=pqvVF5hSEbDO6MlrXHXxDUg This crosswalk reinforces the suggestions in the proposal. We've seen some excellent documentation emerging from various parts of the Evergreen community, and channeling it into an intentional project integrated with larger Evergreen efforts would be excellent. -- -- | Karen G. Schneider | Community Librarian | Equinox Software Inc. The Evergreen Experts | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712 | E-Mail/AIM: k...@esilibrary.com | Web: http://www.esilibrary.com
