14:00:42 <dluch> #startmeeting 2021-09-02 - Documentation Interest Group Meeting
14:00:42 <pinesol> Meeting started Thu Sep  2 14:00:42 2021 US/Eastern.  The chair is dluch. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:00:42 <pinesol> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:00:42 <pinesol> The meeting name has been set to '2021_09_02___documentation_interest_group_meeting'
14:00:52 <dluch> #topic Agenda
14:01:13 <dluch> #info The agenda can be found here:  https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:dig_meetings:20210902-agenda
14:01:14 <dluch> Welcome everyone!  Today's meeting will be business, followed by collaboration and working on documentation, if there's time.
14:01:26 <dluch> #topic Introductions
14:01:26 <dluch> Please paste "#info <username> is <name>, <affiliation>" to identify who you are and what organization, if any, you represent.
14:01:26 <dluch> #info dluch is Debbie Luchenbill, MOBIUS
14:01:45 <abneiman> #info abneiman = Andrea Buntz Neiman, Equinox
14:01:52 <jihpringle> #info jihpringle is Jennifer Pringle, BC Libraries Cooperative
14:01:53 <alynn26> #info alynn26 is Lynn Floyd, Evergreen Indiana.
14:03:08 <dluch> Thank you for coming! If you come in later, feel free to introduce yourself when you arrive.
14:03:12 <dluch> #topic Helpful Information: Documentation contributions and collaboration
14:03:12 <dluch> #info You can find the Documentation Needs List at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:documentation_needs
14:03:12 <dluch> #info DIG Roles can be found at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:digparticipants
14:03:22 <dluch> #topic Old and Ongoing Business
14:03:38 <dluch> #info Check-in - How's everyone doing?
14:03:54 <dluch> Fires? Floods? Earthquakes?
14:04:22 <jweston> #info jweston is Jennifer Weston, Equinox
14:04:22 <jihpringle> we've had rain so the fires in the province are dying down and it's starting to feel like fall
14:04:22 <abneiman> Just another day in 2021, so all of the above, probably :)
14:04:29 <dluch> lol
14:04:40 <dluch> jihpringle: that's good!!
14:05:05 <rhamby_> now I have a James Taylor earwyrm
14:05:05 <jihpringle> yes, I'm embracing fall :)   I'm ready for sweater weather
14:05:30 <alynn26> I have redone the whole section on Workstations.  I just about ready to  commit it all.
14:05:31 <dluch> We finally had a break in the horrible heat and humidity and now it's just awful heat and humidity. Still no rain, though
14:05:35 <jweston> rain and flooding here though the sunshine is out today!  Glad I moved to higher ground
14:05:43 <mantis1> #info mantis = Gina Monti, Bibliomation
14:05:56 <jweston> +1 ready for sweater weather
14:05:58 <dluch> rhamby: mwuahahaha
14:06:21 <dluch> alynn26: awesome!
14:06:25 <alynn26> I am also ready for fall.  Nice rain storms recently. here.
14:06:37 <dluch> #info Previous Action Items
14:06:41 <alynn26> Though out all the old information from the xul client.
14:06:56 <dluch> I think I have an idea, but how are these coming?
14:07:08 <dluch> I'll take them in order...
14:07:25 <dluch> 1. sandbergja will make a video for proof of concept in the Quick Starts section
14:07:29 <Bmagic> #info Bmagic = Blake GH, MOBIUS
14:07:50 <dluch> I'm assuming this isn't done. I'm thinking maybe we should just take it away?
14:07:58 <dluch> (the action item)
14:08:04 <abneiman> +1 to removing the action item
14:08:16 <jweston> +1 remove
14:08:30 <dluch> Cool, done
14:08:34 <alynn26> I know there are some videos out there
14:08:41 <alynn26> but not really looked at them.
14:08:51 <dluch> 2. dluch and jweston will look at the wiki's Documentation Needs List (linked at the beginning) to ensure that undocumented features listed are still relevant in the 3.6 context. Also, go through 3.6 and see what other documentation is missing from it. And also 3.7.
14:09:02 <dluch> I am terrible and have still done nothing with the document jweston created or met with her. I'm sorry! Will actually put it on my calendar this month, not just my priority list, lol.
14:09:20 <alynn26> I know that feeling.
14:09:26 <jweston> dluch: nothing from me (yet) either but let's leave this one on there -- it's a good thing to do
14:09:35 <jihpringle> I'm still up for helping with this as well but it keeps slipping down my list
14:09:39 <dluch> #action dluch and jweston will look at the wiki's Documentation Needs List (linked at the beginning) to ensure that undocumented features listed are still relevant in the 3.6 context. Also, go through 3.6 and see what other documentation is missing from it. And also 3.7.
14:09:47 <dluch> jweston: agreed
14:10:02 <dluch> 3. DIG will investigate Antora's pdf roadmap and its feasibility for Evergreeners to do, and/or other ideas about pdfs
14:10:12 <dluch> Has anyone had a chance to do this?
14:10:30 <dluch> Do we need to form a subcommittee or something to investigate?
14:10:55 <alynn26> It is scheduled for V.3.
14:10:55 <dluch> (though, really, do we have enough people to form a subcommittee, lol)
14:11:09 <alynn26> https://docs.antora.org/antora/2.1/project/roadmap/
14:11:35 <abneiman> well I guess they're a tad behind on that release timeframe
14:11:50 <jweston> heh - just noticed that -- so, do we need to update the dates on the Antora Roadmap?
14:11:57 <dluch> Lol, yeah
14:12:11 <dluch> I suppose pandemicky things interfered
14:12:36 <jweston> indeed
14:12:37 <dluch> Does Antora have an active user community? Bmagic, do you know?
14:12:48 <dluch> alynn26++
14:12:53 <alynn26> Antora 2.1 EOL was 2020/04/25.  So there timeline is really out of date.
14:13:17 <Bmagic> I've not been plugged into their community, not sure.
14:14:02 <dluch> Looks like they have a chat on Zulip? Don't see anything else, though
14:14:27 <dluch> Okay, I'll investigate
14:14:49 <alynn26> I am in the chat, and Antora 3.0.0-alpha.8 has been released!  on August 13th
14:15:16 <jweston> alynn26++ lovely surprise!
14:15:28 <dluch> Oh, cool!!! Do they have it documented somewhere?
14:15:37 <dluch> alynn26++
14:15:47 <abneiman> alynn26++ any sense of 3.0.0 full release timing?
14:16:05 <alynn26> https://docs.antora.org/antora/3.0/whats-new/#antora-3-0-0-alpha-8
14:16:20 <alynn26> No, not that I have found
14:17:33 <dluch> I'm not seeing anything about pdfs there, unless I'm missing it
14:18:47 <abneiman> hmm. and it looks like the alpha.1 was 9/29/2020, so.......
14:20:46 <dluch> Yeah. Disappointing! :-(
14:21:19 <jweston> looks like there are asciidoc extension examples under antora-pdf here:  https://gitlab.com/djencks/antora-extension-examples
14:22:14 <dluch> What version of antora are we on? I can't remember
14:22:34 <alynn26> we are on 2.1 I think
14:23:18 <alynn26> There are several work arounds here: https://gitlab.com/antora/antora/-/issues/349
14:23:50 <alynn26> Bmagic, We may need to investigate some of these.
14:24:55 <dluch> That sounds like a good idea. Shall I make you an action item, alynn26?
14:26:00 <dluch> #action alynn26 and Bmagic will investigate some possible options for adding pdf generating to our documentation site
14:26:10 <dluch> I just did anyway :-D
14:26:31 <alynn26> :P
14:27:02 <dluch> #info  asciidoc extension examples under antora-pdf here:  https://gitlab.com/djencks/antora-extension-examples
14:27:14 <dluch> #info  several work arounds here: https://gitlab.com/antora/antora/-/issues/349
14:27:40 <dluch> I'd like to move on, unless there's more to discuss here?
14:28:16 <dluch> 5. DIG will investigate why anything that is a heading 4 ==== or lower is not rendering properly formatted in Antora. Example: "Sort By Geographic Proximity" at https://docs.evergreen-ils.org/eg/docs/latest/opac/using_the_public_access_catalog.html#_viewing_a_record
14:28:49 <dluch> Did this get figured out? I admit, I completely forgot about it until I went to put together today's agenda
14:29:09 <abneiman> I recall alynn26 said it was something with our CSS but I'm not sure who can fix that
14:30:34 <dluch> CSS for our Antora or is there a bigger Evergreen one?
14:30:55 <abneiman> CSS for the docs site, IIRC
14:32:14 <alynn26> I can look  into the CSS and see what needs changing.
14:32:20 <dluch> It looks like it should be doable -- https://docs.antora.org/antora-ui-default/stylesheets/
14:32:48 <alynn26> I think it is something we changed in our stylesheet, that just needs adjusting.
14:33:31 <dluch> #action alynn26 will look into Evergreen's Antora CSS to see why anything that is a heading 4 ==== or lower is not rendering properly formatted in Antora. Example: "Sort By Geographic Proximity" at https://docs.evergreen-ils.org/eg/docs/latest/opac/using_the_public_access_catalog.html#_viewing_a_record
14:33:40 <dluch> alynn26++
14:34:07 <dluch> That's all I have for old or ongoing business to discuss. Anything I missed that someone would like to talk about?
14:35:02 <abneiman> #4, index page, is another mystery. I filed an LP about it after running into it again the other day: https://bugs.launchpad.net/evergreen/+bug/1941917
14:35:02 <pinesol> Launchpad bug 1941917 in Evergreen "docs: index is not being generated" [Undecided,New]
14:35:55 <dluch> Oh, I completely skipped that one! abneiman++
14:36:22 <dluch> 4. DIG will investigate the index page not generating: https://docs.evergreen-ils.org/eg/docs/latest/shared/index.html
14:36:44 <dluch> Thank you for making a bug report, abneiman!
14:37:44 <abneiman> welcome - literally the least I could do :)
14:38:11 <dluch> #info abneiman filed an LP about the index page not generating: https://bugs.launchpad.net/evergreen/+bug/1941917
14:38:11 <pinesol> Launchpad bug 1941917 in Evergreen "docs: index is not being generated" [Undecided,New]
14:38:17 <dluch> Go add heat! :-D
14:38:39 <dluch> #topic New Business
14:38:48 <dluch> #info Show and Tell Topic for October: Same as August
14:38:59 <dluch> Since only the two presenters (alynn26 and jihpringle), rfrasur, and I were at the August meeting, we decided to move their presentation to October's meeting.
14:39:12 <dluch> The presentation is a demonstration on how to contribute documentation you've already created for something else (aka, your home library/consortium/district), from jihpringle and alynn26.  Do you all have anything you want to add?
14:40:03 <jweston> jihpringle++ and alynn26++ these are great topics and timely
14:40:09 <alynn26> Since I was working on it for the presentation, I went ahead and did the work and alot moret for it to make since.  So, back to the drawing board for the presentation.
14:40:28 <dluch> Lol
14:40:40 <dluch> alynn26++ jihpringle++
14:40:42 <jihpringle> yup, we'll need to find a new piece of documentation for the demo :)
14:41:02 <dluch> #info Docs organization: Review and Re-organize
14:41:11 <alynn26> I had to rewrite the whole workstation adminsitration section, which I am about ready to commit with a few more images to attach.
14:41:31 <jihpringle> alynn26++ for getting rid of xul screenshots
14:41:32 <dluch> Dang. Nice job, alynn26!
14:41:37 <dluch> alynn26++
14:42:12 <dluch> Back to Docs organization...
14:42:13 <dluch> This came up at the August meeting. Now that the docs are moved over to Antora and we're getting more used to it, it's probably time to do a comprehensive review of the existing docs to make sure everything is still accurate, screen shots are up-to-date, etc. We also may want to reorganize where things are.
14:42:36 <alynn26> dluch++
14:42:39 <dluch> (Did I get that right, jihpringle?)
14:42:44 <jweston> dluch++
14:42:50 <jihpringle> yup
14:42:56 <jweston> +1 to comprehensive review
14:43:00 <dluch> This will obviously be a huge project! Does anyone have any ideas for structuring such a thing? I was thinking maybe a shared spreadsheet or doc, and/or maybe having some of our Zoom meetings be us working on it.
14:43:14 <alynn26> especially those pesky XUL screen shots.
14:43:35 <jihpringle> I think we should do it section by section rather than try and tackle the whole thing at once
14:43:40 <jweston> we could ask for assistance from the interest groups for review
14:43:55 <jihpringle> I think that's a great idea jweston
14:43:59 <alynn26> That works for me.  Assistance from them would be great
14:44:13 <dluch> jihpringle++ jweston++ Very good ideas!
14:44:31 <jweston> want me to suggest to the IGs and recruit?
14:44:31 <abneiman> one thing I've noticed is "things in multiple places" vs just linking
14:44:46 <jweston> abneiman so true
14:44:54 <dluch> YES
14:45:09 <abneiman> for example, I'm working on a big revision of AngAcq Admin (based on akilsdonk's docs that she produced for our recent work in that area)
14:45:11 <dluch> jweston: that would be great, thank you!
14:45:12 <jweston> we would want a guide (dare I say checklist) for what and how to review
14:45:22 <jihpringle> agreed
14:45:30 <alynn26> When I redid the Workstation Administration section, there were a lot of duplication, i removed some of it.
14:45:36 <abneiman> there is also info on this page: https://docs.evergreen-ils.org/eg/docs/latest/installation/edi_setup.html
14:45:55 <jihpringle> I'm thinking a google spreadsheet with a page for each section of the doc
14:46:10 <jweston> jihpringle++ sounds great
14:46:19 <abneiman> under "Configuration" it would be more maintanable to just say "hey here's a link to the EDI config page over in Acq Admin" so we're not maintaining two pages
14:46:34 <dluch> #action jweston will ask for assistance on docs review from the interest groups for review and recruitment
14:47:02 <jihpringle> I can start a spreadsheet for tracking
14:47:06 <abneiman> anyway, while we're reorganizing, a general rule of "don't make more work for future us, just use better internal linking" might be helpful :)
14:47:06 <dluch> jihpringle++ sounds great
14:47:29 <jihpringle> +1 to a general rule of "don't make more work for future us, just use better internal linking"
14:47:34 <dluch> +1 to that, abneiman
14:47:52 <alynn26> +1
14:47:57 <jweston> +1 to protecting future us with better linking
14:48:02 <dluch> #action jihpringle will set up a spreadsheet for tracking documentation review
14:48:02 <jihpringle> https://docs.google.com/spreadsheets/d/1nPD0_blC51wVcYJsdQqGYFoRrlcGmbmqbZlrlosaHgE/edit?usp=sharing
14:48:20 <jihpringle> spreadsheet created (no content yet :)  )
14:48:40 <dluch> #info jihpringle has already created the spreadsheet :-D
14:48:42 <jweston> jihpringle++ love the quick "home" for the spreadsheet
14:48:49 <dluch> jihpringle++
14:49:07 <abneiman> fastest action-item execution ever
14:49:41 <dluch> Indeed! lol!
14:50:22 <jihpringle> we could roll the Documentation Needs List review into this
14:50:45 <jihpringle> as sections are reviewed missing chapters can be added to the spreadsheet
14:50:46 <jweston> jihpringle good idea
14:50:47 <dluch> jihpringle: I was just thinking the same thing! That would be great
14:51:13 <dluch> jihpringle++
14:51:35 <jihpringle> I'll put some instructions on the first page so if we have multiple interest groups helping everyone is on the same page
14:51:44 <dluch> (I was not thinking about the missing chapters into sections thing, though--awesome idea!)
14:52:24 <dluch> Sounds good, jihpringle, thanks!
14:53:22 <alynn26> instructions++
14:53:36 <dluch> I want to briefly bring in the next action item, because it's a little relevant to this conversation, unless it's already been done since August (alynn26???)
14:53:46 <dluch> #info Link Bmagic and alynn26's conference presentation to the "How to Contribute" documentation
14:54:00 <dluch> #info Maybe other relevant videos, too, like Chris's reports one, etc.
14:54:39 <alynn26> It's not.  But i'll work on pushing a branch with it out. and Chris's reports one.
14:54:49 <dluch> Sweet, thanks!
14:54:54 <dluch> alynn26++
14:56:00 <jihpringle> related, a big thank you to Bmagic and sandbergj for figuring out why new docs weren't showing up in the 3.6 and 3.7 branches and fixing it
14:56:09 <alynn26> Something to do Monday while I wait on file transfers.  YEA new servers.
14:56:19 <dluch> We are almost out of time... the next item should be quick, too, I think, because Outreach talked about it yesterday.
14:56:29 <dluch> #info How should documentation be in the navigation of the new website design?
14:57:11 <dluch> abneiman: I've misplaced my notes from yesterday...was there anything DIG needed to decide? (or rhamby)
14:57:22 <alynn26> depends on the design I would think
14:58:21 <dluch> (or jweston, lol)
14:58:55 <dluch> Well, we're going to rename it on the main page, but documentation will still be there...
14:59:01 <abneiman_web> seems that our quassel may have fallen over
14:59:16 <dluch> Oh, no! Glad you're back
15:00:00 <dluch> maybe?
15:00:33 <abneiman_web> I'm here on the web gateway, but I missed the last several minutes
15:00:34 <dluch> I think we'll table this for now. I'll let everyone know what/if we need to do anything right now.
15:00:49 <jweston6> I'm back (sort of -- also on web gateway for now)
15:00:50 <dluch> Ah, okay.
15:01:34 <dluch> Anything else for the good of the order?
15:01:53 <abneiman_web> @dluch sorry, was retrieveing notes
15:01:53 <pinesol> abneiman_web: MARC still isn't dead yet, alas
15:02:01 <abneiman_web> dammit pinesol
15:02:12 <dluch> lol
15:02:32 <dluch> abneiman: okay, will wait for notes. :-)
15:02:54 <abneiman_web> anyway. For the website. The proposal is to rename the "documentation" heading as something else (Education, Learning, Training all options)
15:03:19 <abneiman_web> so if DIG has any input there, that's cool
15:03:26 <jihpringle> Resources ??
15:03:31 <abneiman_web> noooooooooooooooooo
15:03:36 <dluch> lololol
15:03:40 <jihpringle> lol
15:03:44 <dluch> abneiman hates resources
15:04:10 <abneiman_web> or at least I hate the term "resources"
15:04:11 <alynn26> my question is what elese is going to be under there.
15:04:18 <abneiman_web> good question alynn26
15:04:42 <dluch> we talked about links to videos, but then I think decided to make that its own page?
15:04:47 <abneiman_web> other links will be to the wiki, to the youtube channel, to collected conference presentations, the roadmap, etc.
15:05:11 <abneiman_web> so, more that documentation, but all in that realm of "hey come learn things"
15:05:17 <abneiman_web> *more THAN
15:05:22 <dluch> Yes!
15:06:27 <dluch> Maybe we could call it "Hey, come learn things!" ;-)
15:06:31 <abneiman_web> Ha!
15:07:47 <alynn26> Hmm in that case, How about Instructions :)
15:08:02 <abneiman_web> anyway if any DIGgers have suggestions for a top-level menu name that encompasses All The Learning Things ... please share with Outreach (me, jweston, dluch, et al.)
15:08:15 <alynn26> Library of learning
15:08:34 <dluch> Ooo, that's a nice one, alynn26
15:08:47 <dluch> But yes, what abneiman said :-)
15:09:05 <jweston6> hmmm... could be Learning Library (yes, keep the suggestions coming!)
15:09:13 <dluch> #info  if any DIGgers have suggestions for a top-level menu name that encompasses All The Learning Things ... please share with Outreach (me, jweston, dluch, et al.)
15:09:18 <alynn26> We were talking about library of things earlier.
15:09:27 <dluch> oops
15:09:31 <jweston6> alynn++
15:09:36 <dluch> #info  if any DIGgers have suggestions for a top-level menu name that encompasses All The Learning Things ... please share with Outreach (abneiman, jweston, dluch, et al.)
15:09:37 <abneiman_web> I like "learning library"
15:09:37 <jweston6> alynn26++
15:09:42 <dluch> alynn26++
15:09:57 <alynn26> jweston++
15:10:03 <dluch> jweston++
15:10:13 <alynn26> I am liking Learning Library.
15:10:20 <dluch> I like that, too
15:10:32 <jihpringle> it seems very appropriate :)
15:11:20 <abneiman_web> jihpringle it does!
15:12:07 <dluch> #info DIGgers present at the meeting like "Learning Library"
15:12:23 <alynn26> +1
15:12:41 <jweston6> +1
15:12:47 <dluch> I know we're past time, but does anyone else need to talk about something (DIG-related :) )?
15:13:09 <abneiman_web> just a tip I discovered for anyone using Notepad++ as an editor
15:13:22 <dluch> Do go on...
15:13:53 <abneiman_web> There's  a "compare" plugin available so just in case you need to compare two 1000+ line adoc files... it gives you a easy-to-understand visual diff between the two
15:14:13 <abneiman_web> anyway, it made my week :)
15:14:16 <dluch> Ooooo
15:14:38 <abneiman_web> http://www.technicaloverload.com/compare-two-files-using-notepad/
15:15:01 <dluch> #info abneiman discovered that There's  a "compare" plugin available so just in case you need to compare two 1000+ line adoc files... it gives you a easy-to-understand visual diff between the two http://www.technicaloverload.com/compare-two-files-using-notepad/
15:15:07 <dluch> abneiman++
15:15:29 <dluch> Okay...Our next meeting will be on October 7, on Zoom. I'll post the link on the agenda about a week prior to the meeting.
15:15:29 <jweston6> abneiman++ very cool
15:15:32 <jihpringle> style question, maybe for discussion next month - "&" or "and" in section headers (we currently have both being used)
15:15:54 <jweston6> dluch++ good meeting!
15:15:58 <dluch> jihpringle++ will add that to the list!
15:16:04 <dluch> Thanks for being here, everyone!
15:16:05 <jihpringle> thanks dluch
15:16:09 <jihpringle> dluch++
15:16:11 <abneiman_web> dluch++
15:16:12 <dluch> #endmeeting