[OPEN-ILS-DOCUMENTATION] DIG 2013 Hack-a-way recap

[Yamil Suarez]

Hello,

I wanted to write about my observations on this years Hack-a-way on Friday, November 15th. I encourage the other participants to share their own observations and comments too.


Participants  
---------------

(I am afraid I may have missed someone, please let me know if I missed you or screwed up your org/state)

Kate Butler - Rodgers Memorial Library (New Hampshire)
Ruth Frasur - Indiana State Library (Indiana)
Erica Rohlfs - ESI (Georgia?)
Ben Shum  - Bibliomation (Connecticut)
Remington Steed - Calvin College (Michigan)
June Caola-Stokoe - C/WMARS  (Massachusetts)
Yamil Suarez - Berklee (Massachusetts)
Jessica Venturo - Bibliomation (Connecticut)


The positives
-----------------
I think the DIG AsciiDoc training was very helpful, specially since it was scheduled before the day of the DIG hack-a-way. For example, I was pleasantly surprised to see two new DIG volunteers with laptops completely or almost completely ready to run the Asciidoc software at the start of the hack-a-way thanks to them watching the DIG AsciiDoc training. The Google "On Air" Hangout appears to have worked OK, and now the training is available on demand.   

We were able to find small tasks for new DIG volunteers to get a chance to edit AsciiDoc documentation. For example, volunteers worked on incorporating new EG features listed in the release notes within the the official docs. As well as getting a chance to practice the process of deciding the best location to use to place the new feature in the official docs. Also during the hack-a-way a couple of volunteers worked on reviewing and updating some older documentation that a Berklee intern worked on last year.

Another set of volunteers (June, Ben, and I) worked on trying to identify older documentation that needs to be converted from the older DOcBook format to the new AsciiDOc format. Ben Shum came up with a great idea of using a three way visual diff view (http://meldmerge.org/) of the older DocBook versions of the docs (versions 1.6, 2.0, 2.1) to more easily find documentation that needs to be moved over to AsciiDoc. Ben also made us realize that when trying to find older DocBook to convert to AsciiDOc, that we don't need to worry about doc versions 2.2 to 2.5 because those have been living within the main EG Git code repository. Therefore those versions (2.2 to 2.5) are mostly the same, except for newer features added little by little. I strongly believe that Remington Steed trying to explain this to me at the DEv Hack-a-way, but I did not understand him at the time.


Things to try to improve
------------------------------

Overall I found it very hard to identify documentation for new volunteers to work on before the start of the DIG hack-a-way. It was easier to assign brand new features listed in the release notes to be included n the official docs. Regretfully it was harder to select older documentation that needed to be converted to AsciiDoc so it can be moved to the latest version. I will explore Ben Shum's visual "diff" approach to find more targets for conversions moving forward. At DIG we already started labeling small/simple documentation needs within Launch Pad as "bitesize," so collectively DIG can keep doing this to have a ready pool of things to assign to new volunteers. 

It caught us off guard that we could not take all of the official documentation AsciiDoc files and be able to build at least the HTML version of the final doc to test our work. I should have tried this years ago, so I could have realized the amount of set up Robert Soulliere (and others) went through to have our nightly ASciiDoc build system. Up to know, I like most DIG volunteers had only been converting individual ASciiDOc files in to HTML to test our syntax. 


Overtly simple list of files worked on
---------------------------------------------

(Again, I may have missed the work of some, so please correct me)

* holds.txt - Jessica
* cataloging.txt - Ruth
* customize_staff_client.txt - Kate
* lsa-library-settings-editor.txt - Jessica
* workstation_admin.txt - Kate
* introduction_to_sql.txt - Ben, June, Yamil
* Addresses on Routing List.txt

Next Actions
----------------

(Please submit your suggestions)

* Make final edits to ASciiDoc files worked on (if necessary)
* Include the files worked on during the 2013 DIG Hack-a-way into the main repository
* Update the DIG wiki with the files/features that were worked on
* Brainstorm on ways to improve the 2014 DIG Hack-a-way
* Brainstorm for next DIG group activity based on hack-a-way experience (the 2014 EG Conference DIG hack-fest) 
* ???


Thanks to all that participated,
Yamil