14:00:20 <sandbergja> #startmeeting Documentation Reorg Planning
14:00:20 <pinesol_green> Meeting started Wed Feb 10 14:00:20 2016 US/Eastern.  The chair is sandbergja. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:00:20 <pinesol_green> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:00:20 <pinesol_green> The meeting name has been set to 'documentation_reorg_planning'
14:00:25 <sandbergja> #chair yboston
14:00:25 <pinesol_green> Current chairs: sandbergja yboston
14:00:33 <sandbergja> Welcome everybody!
14:00:46 <krvmga> #info krvmga = Jim Keenan, C/W MARS
14:00:49 <sandbergja> Thanks for joining us for our second meeting to discuss reorganizing the official eg docs
14:00:55 <sandbergja> #topic Introductions
14:01:10 <sandbergja> Feel free to introduce yourself using the #info command
14:01:23 <krvmga> sorry. :) jumped the gun with my info
14:01:23 <sandbergja> #info sandbergja is Jane Sandberg, Linn-Benton Community College
14:01:26 <alynn26> #info alynn26 is Lynn Floyd, Anderson County Library, SCLENDS
14:01:38 <sandbergja> krvmga: no worries :-)
14:01:39 <Christineb> #info Christineb is Christine Burns - BC Libraries Cooperative / Sitka
14:01:44 <akilsdonk> #info akilsdonk is Angela Kilsdonk, Equinox Software
14:01:53 <jihpringle> #info jihpringle is Jennifer Pringle - BC Libraries Cooperative / Sitka
14:01:53 <yboston> #info yboston is Yamil Suarez @ Berklee College of Music
14:02:02 <yboston> The agenda can be found here
14:02:10 <yboston> #link http://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:reorg_2014:agenda_2016-02-10
14:02:12 <remingtron> #info remingtron is Remington Steed, Hekman Library (Calvin College)
14:02:16 <remingtron> (mostly listening)
14:02:39 <jck_> #info jck is Joan Kranich, C/W MARS
14:03:01 <sandbergja> Welcome, everyone! Just to orient everybody, yboston and I will be co-leading this meeting
14:03:24 <sandbergja> If you have a web browser handy, please open up the agenda, which yboston just posted
14:03:53 <sandbergja> And also the draft requirements doc; I think those both will be useful as jumping-off points for our discussion
14:03:59 <sandbergja> #link http://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:reorg_2014:requirements
14:04:24 <sandbergja> #topic Develop consensus on project requirements
14:04:47 <sandbergja> First of all, I want to make sure our goals and values all sound good to everyone
14:04:54 <sandbergja> before moving on with such a big project!
14:04:57 <sandbergja> Initial thoughts?
14:05:41 <krvmga> i think the requirements doc covers everything i was thinking of
14:05:48 <yboston> I think you did an excelent job with these requirements
14:06:05 <sandbergja> aww, shucks!  Thanks, yboston
14:06:11 <krvmga> yes, excellent
14:06:13 <alynn26> I think these are obtainable requirements
14:06:22 <Christineb> I agree with the requirements
14:06:42 <akilsdonk> The requirements look great.
14:06:56 <sandbergja> remingtron also suggested that we gather ideas from actual eg users using a survey
14:07:24 <yboston> I had a question about a requierement that mentioned content that gets repeated in more than one palce. let me look for it. Go ahead in the meantime
14:07:33 <sandbergja> Sounds good
14:07:37 <alynn26> I like the idea of a survey, to see what they think is missing in the docs.
14:07:45 <jihpringle> yboston: this I think "The exact same content must be present in multiple books without needing to be updated separately (e.g. a chapter about the Evergreen community, or an introduction to the client interface)"
14:07:58 <alynn26> Or what can they not find that is actually in there
14:08:36 <sandbergja> alynn26: good point
14:08:44 <remingtron> alynn26: right, there's the issue of usability, not just content
14:08:59 <yboston> jihpringle: yes, now that I reread it I am all set. I misunderstood it the last time I read it. Ai gree with it
14:09:21 <jihpringle> I agree with it too, but is it technically possible?
14:09:50 <yboston> in some situation it shoudl be possible, depednign on how we set up the strucuee of the files and "books"
14:10:00 <sandbergja> jihpringle: Excellent question.
14:10:27 <sandbergja> I want to thank remingtron for coming up with survey questions
14:10:38 <yboston> one concer I hve is that as we experiment we will be happy with the docs in ne format, e.g. HTML, but not as happy in PDF
14:10:53 <remingtron> sandbergja: those are just a draft! I welcome edits, suggestions, etc.
14:11:19 <jihpringle> is there a link to the survey questions?
14:11:40 <sandbergja> yboston: do you think we should hammer out some more specific requirements for PDF version, HTML version?
14:11:53 <sandbergja> jihpringle: they are in the agenda, under requirements
14:11:57 <jihpringle> thanks
14:12:40 <yboston> sandbergja: at some point we shoudl address the acceptable setup /behavior of each format, but at this point it might be OK to focus on regenral requriements
14:12:49 <yboston> *general
14:13:10 <sandbergja> sounds good
14:13:30 <alynn26> I think those are great starting questions.
14:13:39 <sandbergja> Would somebody be willing to add some survey questions that get at alynn26's concerns about findability and missing content?
14:13:55 <sandbergja> Or do we like keeping it pretty general?
14:14:53 <remingtron> sandbergja: I'll post a few more questions taken from another open source project's recent docs survey
14:14:57 <krvmga> just to make sure i'm not confused...the survey would be about the documentation (or sections of the documentation) as it exists now?
14:16:44 <sandbergja> krvmga: as I read it, it asks about documentation in general, and best practices that our end users appreciate
14:16:49 <remingtron> krvmga: I was thinking of a more broad survey of what users need from documentation
14:17:18 <remingtron> sandbergja: right
14:17:47 <sandbergja> Can I start moving the survey conversation toward some action items?
14:18:03 <sandbergja> Remingtron, can I say that you will add some more questions from the other project you mentioned?
14:18:16 <remingtron> sandbergja: yes
14:18:48 <sandbergja> #action remingtron will post a few more questions to the survey in the agenda, informed by another open source project's recent docs survey
14:19:19 <sandbergja> Is anybody willing to put together, publicize, or gather results from an end-user survey?
14:19:31 <jihpringle> I think it would make sense to have it open for others to add questions as well and then cull it down to the list we actually want to send
14:20:09 <sandbergja> jihpringle: Maybe a page on the wiki?
14:20:27 <krvmga> would it make sense to ask in the survey what kind of role respondents fulfill (like, are they local system people, front line staff, etc.)
14:20:33 <alynn26> once we get the questios down, I can place it surveyMonkey
14:21:08 <sandbergja> krvmga: sounds good to me!
14:21:18 <sandbergja> alynn26++
14:21:42 <jck_> Asking for the role respondents fulfill would be helpful
14:21:55 <sandbergja> #action alynn26 will put the survey on surveymonkey once we have questions solidified
14:22:32 <sandbergja> jck_, I agree.  Also, respondents should be able to check multiple boxes, because at small libs, people might be catalogers, circulators, admins, all at once!
14:22:50 <jck_> I agree
14:23:02 <jihpringle> +1
14:23:13 <jck_> Do we want to know if their system is hosted?
14:23:52 <sandbergja> Is anybody willing to set a deadline for a final set of questions and encourage participation in crafting survey questions from DIG members?
14:23:59 <jihpringle> or we could ask who is their front line support - in house versus outside
14:24:00 <remingtron> jck_: yes, another great question to include
14:24:10 <sandbergja> jck_++
14:24:45 <yboston> on the topic of the deadline, should we wait for after the next EG release?
14:25:08 <remingtron> maybe we should ask the oversight board if they have any suggestions for such a survey. They may know other key questions we should include.
14:25:22 <sandbergja> remingtron: good idea
14:25:30 <jihpringle> how about March 2nd for compiling the questions and getting them down to a final list? - that gives us three weeks
14:25:40 <sandbergja> Sounds good to me
14:25:43 <yboston> me too
14:25:50 <jck_> sounds good
14:26:03 <krvmga> +1
14:26:25 <sandbergja> #agreed We will compile docs survey questions for end users by March 2nd
14:26:55 <jihpringle> I can create a wiki page for compiling the questions and link it back to the re-org page
14:27:14 <sandbergja> jihpringle++
14:27:31 <sandbergja> #action jihpringle will create a wiki page for compiling the survey questions and link it back to the re-org page
14:27:50 <sandbergja> And I can volunteer to bug people for their input before March 2!
14:28:17 <sandbergja> #action sandbergja will encourage input on survey questions from DIG members
14:28:37 <yboston> jihpringle++
14:28:52 <sandbergja> I can also volunteer to touch base with the oversight board, if we'd like to do that
14:29:51 <sandbergja> #action sandbergja will touch base with the oversight board about our survey instrument
14:30:08 <yboston> I am on the board, I can with that, but I need the exact wording before hand
14:30:22 <yboston> *I can help with that
14:30:43 <sandbergja> yboston: thanks!  How about I come up with language and send it your way, then?
14:30:50 <yboston> perfect
14:30:58 <yboston> we have a meetign next week
14:31:14 <sandbergja> Thanks for a fruitful conversation so far.  Okay if we move on to some specific questions?
14:31:35 <remingtron> sandbergja: go for it
14:31:53 <sandbergja> #topic What platform to use for re-organized docs
14:32:27 <sandbergja> We've been looking for an asciidoc solution, but at our last meeting, we also had some interest in flossmanuals
14:32:37 <sandbergja> Any thoughts there?
14:33:02 <jihpringle> I vote for whatever is going to be easiest for the largest number of people
14:33:06 <yboston> I don't have much exepreince in flossmanual
14:33:13 <sandbergja> I don't know anything about flossmanuals, so I am happy to table this until we have some time to read up more on flossmanuals
14:33:20 <yboston> those in DIG that went to that Google hosted event did get a  lot more
14:33:35 <kmlussier> flossmanual is very easy to use
14:33:47 <yboston> I suspect that we can for now just stick to asciidoc to when we start to experiment
14:33:53 <krvmga> we used flossmanual during our docsprint when we wrote the evergreen in action book
14:34:01 <kmlussier> It's as easy as creating a WordPress blog post. You don't need to know any special markup, you just focus on the writing.
14:34:11 <akilsdonk> I agree with using what is going to be easiest for the largest amount of people.
14:34:13 <yboston> though as we investigate the "cross-linsk" we might be more opinionanted on which solution we woudl liek to have
14:34:23 <remingtron> I would hesitate to use something different from asciidoc unless we know how it will be maintained and by whom.
14:34:33 <sandbergja> kmlussier and krvmga, how easy is it to do small, incremental changes?
14:34:48 <kmlussier> It's a matter of clicking Edit, making the change, and then saving.
14:34:54 <krvmga> it is easy
14:35:00 <sandbergja> Does it track version history and all?
14:35:03 <yboston> also, how well does flossmanual handle PDF/epub versions? is it done nightly?
14:35:04 <kmlussier> The problem, of course, is then converting it to Asciidoc
14:35:18 <krvmga> what kmlussier said..
14:35:19 <remingtron> The "Evergreen In Action" flossmanual (that kmlussier and krvmga are talking about) has fallen out of DIG's orbit
14:35:32 <krvmga> it's out of date now
14:35:41 <kmlussier> If you ultimately want the docs to be in Asciidoc, that is. However, I don't think it's any different from converting Word documents, which is something that DIG also accepts.
14:36:41 <remingtron> Also, we already have lots of docs in asciidoc that we could simply reorganize into these separate books, rather than copy/pasting into flossmanuals
14:36:42 <jeff> as a data point, the most recent news post on the flossmanuals site is from October 2014.
14:37:10 <krvmga> personally, i think it's okay to stick with asciidoc atm
14:37:46 <sandbergja> I'm hearing some consensus that asciidoc is the way to go
14:37:51 <sandbergja> any dissent?
14:38:06 <yboston> I think we might be OK to stick with asciidoc at this early junction, but of course if folks want to submit sample orgnaization layouts in another format that should be fine
14:38:10 <jeff> and 50% of the thumbnails on their bookstore are broken images. drat.
14:38:23 <sandbergja> jeff: good to know!
14:38:24 <yboston> jeff++
14:38:32 <sandbergja> yboston++
14:38:48 <sandbergja> Cool!
14:38:58 <sandbergja> #topic Crosslinks in asciidoc
14:39:13 <sandbergja> yboston: would you like to introduce this topic?  You've put a lot of thought into it.
14:39:55 <krvmga> i think it's funny that "Evergreen in Action" is still listed as "new" on flossmanuals
14:40:20 <yboston> yes
14:40:37 <jck_> is the official documentation at open-ils in asciidoc?
14:41:02 <yboston> one of the requirements is that it would be easy to jump around sections in one bok to another
14:41:31 <yboston> I bet this will be easy to do in the HTML format, but it could get tricky with the PDF and epub format
14:41:33 <krvmga> jck_: yes
14:41:42 <jck_> thanks
14:42:06 <remingtron> #link https://github.com/evergreen-library-system/Evergreen/tree/master/docs
14:42:15 <remingtron> jck_: there's a link to the asciidoc files
14:42:16 <yboston> here is the text "We would like an "automated solution" creating see also references that can jump between books and "that does not depend on a human to create the cross links for the HTML version"
14:42:20 <sandbergja> remingtron++
14:43:13 <yboston> so we need to be prepared to compormise on the epub and the PDF version
14:43:41 <yboston> there has been talk of making these "cross-links" somehow point to the HTML version when using a PDF
14:43:51 <yboston> but at this point I don't know how feasable that is
14:43:53 <sandbergja> So, I think the goal with the PDF version is just something that is pretty and can sit at a desk, all printed out
14:44:11 <krvmga> sandbergja: yes, i think so, too
14:44:16 <sandbergja> There was a lot of interest last time in the PDF version being a "desk copy"
14:44:43 <jihpringle> I know that it can be nice to have a printed doc, but we have actively being encouraging out libraries to not print out our manual since it can go out of date so quickly as more info is added
14:44:55 <jihpringle> we only recommend that our libraries print out the section on offline
14:44:58 <yboston> we still should be mindful that when there are cross links to another "book" that the cross link explains where the cotnent can be found, like book / page, etc
14:46:09 <sandbergja> So, yboston, the PDF version of the circulator book might display "Please see the Local Sysadmin manual for more information about circ rules"?
14:46:16 <yboston> for example, this happened often witht he manuals for a previous ILS. the print version would mention the 1) name of book 2) chapter (?)  3) section
14:46:17 <sandbergja> Rather than an actual link?
14:46:48 <sandbergja> Or "Please see chapter 7 of the Local Sysadmin manual for more information about circ rules"?
14:46:56 <yboston> at this point I am not sure how a link in a PDF to another PDf will work
14:47:29 <sandbergja> jihpringle: do your staff prefer the HTML or PDF versions when working online?
14:47:30 <yboston> sandbergja: the exampel you gave might work, though we may not want to mention a chapter number, since those can change after the fact
14:48:13 <yboston> oen thig is, that we might want to be pretty sure of the "book" names before we start marking the cross links
14:48:25 <jihpringle> sandbergja: I believe most of them use the html version but we do have a pdf version as well
14:48:26 <krvmga> yboston: yes
14:48:29 <sandbergja> yboston, good point
14:48:30 <remingtron> sandbergja: that's a great question for a user survey :)
14:48:36 <sandbergja> Very true
14:49:27 <yboston> I like the PDF version to search for a particualr keyword inside a particuar version
14:50:03 <sandbergja> yboston: yes, I like that too
14:50:16 <yboston> (sorry for all the misspellings, happens when I type fast)
14:50:39 <krvmga> yboston: spelling counts toward your final grade. :)
14:51:01 <sandbergja> We have 10 minutes left, and there are 2 things I'd like to cover. :-(
14:51:41 <sandbergja> #startvote How should we spend the rest of our time? Talking about what specific books we'd like to see, Identifying "content coordinators" who would be responsible for compiling specific books
14:51:41 <pinesol_green> Begin voting on: How should we spend the rest of our time? Valid vote options are Talking, about, what, specific, books, we, d, like, to, see, Identifying, content, coordinators, who, would, be, responsible, for, compiling, specific, books.
14:51:41 <pinesol_green> Vote using '#vote OPTION'. Only your last vote counts.
14:51:50 <sandbergja> #endvote
14:51:51 <pinesol_green> Voted on "How should we spend the rest of our time?" Results are
14:51:54 <sandbergja> nope, that didn't work
14:52:02 <sandbergja> trying to get too fancy with meetbot!
14:52:06 <sandbergja> oops!
14:52:10 <krvmga> #vote pick which book to start on
14:52:28 <sandbergja> Yes, let's just go with krvmga's suggestion
14:52:35 <sandbergja> #topic Which book should we start on?
14:52:53 <krvmga> circ +1
14:53:35 <yboston> I would argue we should do circ but for two audiences, client admin and frontline staff
14:53:51 <yboston> so we can get early practice at splitting that type of content by audience
14:54:02 <krvmga> yboston++
14:54:04 <krvmga> i agree
14:54:05 <yboston> or just do one of those two audience at the very beguining
14:54:27 <krvmga> do we want to have teams tackle each one?
14:54:37 <sandbergja> krvmga++
14:54:51 <sandbergja> I like the idea of teams; how do we form them?
14:55:05 <krvmga> who is interested in front line circ docs?
14:55:16 <krvmga> who is interested in client admin docs?
14:55:22 <jihpringle> I would vote to have client admin cover more than just circ but have sections within (circ, cataloguing, etc.)
14:55:38 <jihpringle> and we can add the additional sections as we get to each book
14:55:50 <krvmga> jihpringle: i like that idea
14:55:53 <remingtron> jihpringle: +1
14:56:05 <Christineb> jihpringle: +1
14:56:06 <akilsdonk> jihpringle++
14:56:12 <sandbergja> jihpringle++
14:56:12 <Christineb> I am interested in client admin docs
14:56:22 <jihpringle> I'm also interested in client admin docs
14:56:24 <sandbergja> I am also interested in client admin
14:56:38 <krvmga> that's three for client admin, starting with the circ sectio
14:56:40 <krvmga> n
14:56:55 <krvmga> who's up for frontline circ staff?
14:56:59 <sandbergja> Anyone for front-end circ?
14:57:19 <krvmga> no front desk love? :)
14:57:24 <sandbergja> :-)
14:57:26 <yboston> I can do front end
14:57:29 <akilsdonk> I'm willing to work on frontline circ docs
14:57:35 <krvmga> me, too.
14:57:41 <sandbergja> yboston++ akilsdonk++ krvmga++
14:57:58 <krvmga> do we want to have each team's members contact each other outside irc and divide up labor?
14:58:16 <yboston> though I wondered the two teams shoudl coordinate what belongs where, thoguh for the most part it should be pretty obvious
14:58:18 <sandbergja> krvmga: sounds good
14:58:43 <sandbergja> what if each team does its own thing, and then we compare notes when we are done?
14:58:47 <krvmga> yboston: i think so, too, but some might think there's crossover. receipt templates, for example.
14:58:48 <yboston> the teasm can have an IRC meetign or a google hangout meeting
14:58:59 <jihpringle> and what version of Evergreen are we looking at?
14:59:18 <sandbergja> jihpringle: good question
14:59:21 <krvmga> i think we should use the latest available
14:59:24 <yboston> we can also haev a wiki page with the current wiki outline a claim dibs :) to egt the conversations tarted
14:59:35 <krvmga> yboston++
14:59:37 <yboston> maybe "master" version
14:59:48 <sandbergja> master sounds good
15:00:05 <remingtron> one comment about front lines circ: Since Evergreen 2.10 should include a production web client for circ desk use, I think all future circ docs should include web client versions
15:00:11 <krvmga> the teams don't have to be exclusive. anyone else who wants to join in should feel free.
15:00:15 <jihpringle> at this point are we just coming up with a table of contents for the two books?
15:00:23 <krvmga> remington: good point
15:00:40 <krvmga> remingtron: sorry
15:00:48 <sandbergja> jihpringle: I think so
15:00:52 <remingtron> krvmga: no offense taken :)
15:01:13 <krvmga> :)
15:01:19 <remingtron> jihpringle: and identifying existing docs that can be used
15:01:50 <sandbergja> #agreed A front-line circ team (krvmga, yboston, akilsdonk) and a client admin team (Christineb, jihpringle, sandbergja) will start work on TOCs
15:02:01 <sandbergja> We've reached the one-hour mark
15:02:10 <jihpringle> do you want me to create the wiki pages?
15:02:22 <krvmga> jihpringle++
15:02:25 <sandbergja> jihpringle, if you don't mind, that'd be lovely!
15:02:29 <sandbergja> jihpringle++
15:02:37 <sandbergja> I'm excited about the direction this is going!
15:02:42 <krvmga> do we want to schedule a progress meeting?
15:02:48 <yboston> yes
15:03:44 <sandbergja> I can volunteer to create a doodle poll for a progress meeting
15:03:52 <krvmga> sandbergja++
15:04:01 <sandbergja> #action sandbergja will create a doodle poll for a progress meeting
15:04:05 <jck_> sandbergja++
15:04:17 <sandbergja> Thanks, everyone!
15:04:25 <krvmga> DIG++
15:04:36 <sandbergja> I'm going to close the meeting
15:04:42 <krvmga> thanks, all!
15:04:43 <sandbergja> #endmeeting