14:00:19 <dluch> #startmeeting 2020-05-07 - Documentation Interest Group Meeting
14:00:19 <pinesol> Meeting started Thu May  7 14:00:19 2020 US/Eastern.  The chair is dluch. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:00:19 <pinesol> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:00:19 <pinesol> The meeting name has been set to '2020_05_07___documentation_interest_group_meeting'
14:00:30 <dluch> #topic Agenda
14:00:53 <dluch> #info The agenda can be found here:  https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:dig_meetings:20200507-agenda
14:00:53 <dluch> Welcome everyone!  Today's meeting will be business, followed by collaboration and working on documentation, if there's time.
14:01:03 <dluch> #topic Introductions
14:01:14 <dluch> Please paste "#info <username> is <name>, <affiliation>" to identify who you are and what organization, if any, you represent.
14:01:21 <dluch> #info dluch is Debbie Luchenbill, MOBIUS
14:01:26 <jihpringle> #info jihpringle is Jennifer Pringle, BC Libraries Cooperative (Sitka)
14:01:44 <abneiman> #info abneiman is Andrea Buntz Neiman, Equinox
14:03:18 <rfrasur> #info rfrasur is Ruth Frasur, Evergreen Indiana / ISL
14:03:34 <alynn26> #info alynn26 is Lynn Floyd, Evergreen Indiana
14:04:01 <rfrasur> (I meant to put ECDI - not ISL, but I guess that's accurate too)
14:04:16 * dluch is listening to a recording of sounds in a library and rain on the roof. It is oddly comforting in my home office. :-)
14:04:32 <rfrasur> ++
14:04:37 <rfrasur> normal_sounds++
14:04:44 <remingtron> #info remingtron is Remington Steed, Hekman Library (Calvin University)
14:04:52 <dluch> rfrasur: :-D yep
14:04:52 <remingtron> (mostly lurking today)
14:05:34 <Bmagic> #info Bmagic = Blake GH, MOBIUS
14:05:44 <dluch> Thank you all for coming! If you come in later, feel free to introduce yourself when you arrive.
14:05:58 <dluch> #topic Helpful Information: Documentation contributions and collaboration
14:06:06 <dluch> #info You can find the Documentation Needs List at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:documentation_needs
14:06:15 <dluch> #info DIG Roles can be found at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:digparticipants
14:06:23 <dluch> That's all just FYI for folks (and the minutes)
14:06:32 <dluch> #topic Old and Ongoing Business
14:06:45 <dluch> #info Check-in - How is everyone doing?
14:06:54 <dluch> Are we all still working at home/closed to the public?
14:07:04 <alynn26> Still at home.
14:07:13 <remingtron> Yup
14:07:30 <abneiman> hanging in there. dluch++ for having this question on the agenda :)
14:07:45 <alynn26> We are starting to Open libraries back up. Most are doing sometype of Curbside pickup
14:07:45 * dluch blushes
14:07:46 <Bmagic> yep, at home
14:08:00 * rfrasur is home
14:08:13 <dluch> Yep, we're at home, though our libraries are starting to plan to open/open
14:08:42 <jihpringle> I work from home normally, but our libraries are libraries have all been closed.  We're starting to help them with curbside now
14:09:15 <dluch> curbside++
14:09:53 <dluch> I'm glad that the weather, overall, has been really nice here, so I can walk outside and sometimes have windows open
14:10:22 <dluch> Okay, next topic...
14:10:24 <dluch> #info Previous Action Items
14:10:35 <dluch> How are we doing on these? Has anyone had time for anything outside of COVID Chaos?
14:10:48 <dluch> I'll take them in order...
14:10:58 <dluch> #1 sandbergja will make a video for proof of concept in the Quick Starts section
14:11:07 <dluch> I don't think sandbergja is here?
14:11:27 <jweston> #info jweston is Jennifer Weston, Equinox and she's sorry she is late
14:11:40 <dluch> #action sandbergja will make a video for proof of concept in the Quick Starts section
14:11:47 <dluch> No worries, jweston!
14:11:57 <remingtron> Welcome jweston :)
14:11:58 <dluch> #2 everyone will review all of the docs on Antora, looking for broken things and other fixes needed and report on Launchpad
14:12:03 <dluch> Anyone?
14:12:54 <remingtron> The agenda mentions "Meta data "Untitled" pages still exist", anyone seen that? I haven't yet.
14:13:01 <dluch> We may address some of this in a minute, so I'm not going to keep this as an action item right now.
14:13:04 <abneiman> no :-/
14:13:17 <remingtron> Sounds good dluch
14:13:27 <dluch> #3 DIG will work on 3.5 documentation during Bug Squashing Week, March 16-20
14:13:36 <dluch> We talked about this at the last meeting, and no one had really had time to do this, which is totally understandable.
14:13:44 <Bmagic> the untitled pages (lloks like) are due to the heading levels starting too low
14:13:47 <dluch> More on this later.
14:13:57 <rfrasur> And Bug Squash week got kinda squashed.
14:14:15 <dluch> rfrasure, yup, lol
14:14:20 <dluch> #4 bmagic will think about and explore how to query our git repo to see if there are any non-merged branches that touch /doc/* files
14:14:33 <dluch> bmagic: how'd that go?
14:14:36 <Bmagic> That went
14:14:44 <rfrasur> lol
14:14:45 <Bmagic> and the conclusion was zilch
14:14:49 <dluch> lol
14:14:54 <alynn26> lol
14:14:58 <dluch> So that's good, right?
14:15:37 <Bmagic> gmcharlt++ # handy bash loop, sub loop
14:15:39 <alynn26> bmagic++
14:15:45 <dluch> bmagic++
14:16:00 <jihpringle> for #3 - we're in the process of updating the Sitka manuals to 3.5 (we upgrade on May 19th) so we'll have docs that can be contributed back later (including a section on the experimental catalogue)
14:16:00 <dluch> I'm assuming we don't need to keep this action item
14:16:14 <Bmagic> The idea was to find any non-merged documentation branches - the git investigation turned up none (for me)
14:16:17 <dluch> jihpringle++
14:16:23 <abneiman> jihpringle++
14:16:31 <alynn26> +1
14:16:38 <jweston> jihpringle++ doc on experimental catalogue
14:16:42 <dluch> sitka++
14:16:57 <jihpringle> it doesn't exist yet, but it will as of next Tuesday :)
14:17:11 <alynn26> jihpringle++ sitka++
14:17:16 <dluch> bmagic, so...is that good and do we need to keep the action item?
14:17:41 <Bmagic> I think it can turn into an email to the list
14:17:53 <dluch> Okay
14:18:05 <dluch> All of that flows nicely into the next few items, which kind of go together
14:18:15 <dluch> #info Antora progress
14:18:24 <Bmagic> "hey, we are replacing the old docs folder structure, which will break any git branch edits you may have - merge now or forever hold your peace"
14:18:37 <dluch> lol
14:18:56 <dluch> Last meeting, bmagic said that it's up, eg-docs.georgialibraries.org/prod/, and Antora docs are on it.
14:19:00 <dluch> We still needed to transfer the older docs. Did anyone have time to work on it?
14:19:20 <Bmagic> I used my mind for awhile, didn't write anything yet :)
14:19:29 <Bmagic> (to slurp the old stuff)
14:19:39 <alynn26> lol
14:19:41 <dluch> bmagic also added a bunch of points to this line item. We'll take them one at a time in a minute.
14:19:48 <dluch> bmagic lol
14:20:10 <dluch> I did not even think about the docs, lol
14:20:38 <jweston> I confirmed the doc link still works so that's something
14:20:49 <dluch> jweston++
14:21:21 <dluch> Alrighty, bmagic: you get to lead this part of the discussion
14:21:28 <dluch> #info Meta data "Untitled" pages still exist
14:21:35 <Bmagic> main page:  http://eg-docs.georgialibraries.org/prod/docs/latest/shared/about_this_documentation.html is a prime example
14:21:54 <rfrasur> I'm using that line "I used my mind for awhile, didn't write anything yet."
14:22:08 <Bmagic> the untitled pages (looks like) are due to the heading levels starting too low/high
14:22:32 <dluch> rfrasure: +1 :-D
14:22:41 <dluch> rfrasur: +1 :-D
14:23:05 <dluch> So, like where it says Untitled::Evergreen in the browser tab?
14:23:08 <Bmagic> == About This Documentation ==  needs to be: = About This Documentation =
14:23:11 <Bmagic> should take care of it
14:23:35 <Bmagic> right - the level 0 heading becomes the title of the page
14:23:53 <Bmagic> I am working on a script to hunt these down
14:24:04 <dluch> So someone just needs to go in and change it?
14:24:14 <dluch> Oh, scripting is awesome
14:24:22 <Bmagic> yes - but depending on the page, there might be sub headings that need to follow suit
14:24:45 <Bmagic> so "==" -> =" - then "===" -> "=="
14:24:45 <dluch> That need to be raised up a level?
14:24:53 <Bmagic> yepper
14:24:54 <dluch> lol, yeah, okay
14:25:39 <Bmagic> I'll work out a list of affected pages and see if I can't handle it. If not, I'll share the list and we can all attack
14:25:48 <dluch> So, if you're writing a script to id the places this exists, are you going to export it somewhere for us to work on
14:25:49 <alynn26> thanks
14:25:56 <dluch> Hahaha
14:26:11 <dluch> bmagic: we are on the same wavelength
14:26:38 <Bmagic> wavelength's are sweet
14:27:16 <dluch> #action bmagic is writing a script to identify places in Antora docs that need headers raised up a level. DIG will help with making the changes then.
14:27:20 <alynn26> we will need to update the style guide to reflect this.
14:27:40 <dluch> alynn26++
14:27:50 <dluch> I can do that, unless someone else wants to
14:28:43 <dluch> #action dluch will update the style guide to reflect new header stuff
14:28:58 <dluch> (my brain spaced what I meant to say there, so stuff will do)
14:29:07 <dluch> bmagic++
14:29:19 <dluch> #info Should the server-side generation script(s) be in the EG repo?
14:29:45 <Bmagic> yeah - should it?
14:29:51 <Bmagic> I vote yes
14:29:55 <dluch> lol
14:29:56 <alynn26> I vote yes
14:30:52 <Bmagic> keeping all server-related doc generation scripts should go into the repo for preservation IMO - we don't have that currently, and it's a bit confusing needing to ask around about it
14:31:25 <dluch> sounds reasonable to me
14:31:43 <Bmagic> The only reason we wouldn't might* be privacy? Some of the scripts might mention real paths on the doc server where things will be rsynced/generated...
14:31:52 <dluch> any other discussion around the idea? Any reasons we wouldn't want to?
14:32:38 <Bmagic> it wouldn't be generic.... could mention real URL's like "http://eg-docs.georgialibraries.org" etc
14:33:03 <abneiman> Bmagic: what is the security risk there?
14:33:31 <Bmagic> revealing publicly the file system path on the server is the only thing I can think of
14:34:02 <dluch> I'm not understanding why that's a security risk?
14:34:50 <Bmagic> I don't really know for sure if it is, just that it would be there
14:34:59 <Dyrcona> If it's not generic enough to let someone build it on their own, I might be opposed to adding it to the main repository. Is there a reason that the documentation generation tools cannot have their own repository?
14:36:00 <Bmagic> the site is static HTML, no scripts, so in theory, no hacker could do anything server-side, but Intel had a security issue on the CPU die
14:36:20 <Bmagic> so, anything is possible these days
14:37:20 <dluch> I am not knowledgable on the repositories. Can anyone address Dyrcona's question?
14:37:43 <Bmagic> Dyrcona: the scripts don't exist yet - probably re-eval once we've got something working - one thing is pretty clear: site.yml will need to mention the URL root
14:38:17 <Dyrcona> Bmagic: site.yaml could be generated at build time, too, like other things.
14:38:23 <Bmagic> and needs committed to the repo for Antora to work - so we can't just change the line at run time
14:38:58 <Dyrcona> I'm just pointing out that there may be some resistance from core devs about adding more to the main Evergreen code base, particularly for something that is used in only 1 place.
14:39:16 <dluch> So, can we move on and revisit this when scripts ARE written?
14:39:32 <Bmagic> probably a good idea - let's talk about it once we have the code we need
14:39:35 <Dyrcona> dluch: That would be my recommendation. :)
14:39:42 <abneiman> +1 to revisiting & perhaps consulting some more core committers
14:39:56 <alynn26> +1 for revisiting
14:40:13 <dluch> Okay, good
14:40:42 <dluch> #action We will revisit the topic "#info Should the server-side generation script(s) be in the EG repo?" when scripts are done
14:41:52 <dluch> bmagic, we have 20 minutes left. Are there items on your list that are particularly important to talk about today?
14:42:55 <Bmagic> lets see how far we can get?
14:43:02 <Bmagic> or you want to skip down to d. ?
14:43:08 <dluch> Well, we have other things to talk about besides your items, lol
14:43:44 <dluch> Yeah, so let's go to
14:43:45 <dluch> #info 3.5 Documentation
14:43:57 <dluch> As mentioned above, none of us got to this before the last DIG meeting.
14:44:05 <dluch> Anyone had time since the April meeting?
14:44:15 <dluch> Are there any critical things to get done before the 3.5 release?
14:44:48 <jihpringle> there aren't a lot of big visible changes between 3.3 and 3.5
14:45:02 <dluch> And, as per bmagic, it looks like we missed 3.5 for Antora, I think
14:45:15 <Bmagic> see dev meeting minutes
14:45:41 <jihpringle> (we're jumping from 3.3 to 3.5 so haven't really looked at 3.4)
14:46:16 <abneiman> I have some docs for the features we wrote for 3.5 - was unsure where to put them (and TBH didn't have time to really dive into it)
14:47:12 <dluch> abneiman: where to place them in the docs or where the docs are into which they should be put?
14:47:21 <dluch> (did that make any sense, lol?)
14:47:59 <abneiman> um. no, LOL. but what I meant was - with all the changes w/r/t Antora, I wasn't sure if I should be committing them to the regular docs branch or hold off.
14:48:59 <dluch> haha, that's what I was trying to get at, in my incomprehensible way.
14:49:04 <abneiman> :)
14:49:13 <dluch> What do we all think?
14:49:21 <dluch> (or know?)
14:49:39 <abneiman> I'd been meaning to touch base with sandbergja about it but honestly haven't had a chance
14:50:01 <alynn26> Commit to regular docs, would be my opinion.  As we will still be using that for 3.4 and 3.5
14:50:02 <rfrasur> If it's stuff for 3.5 and there's been a miss of including Antora in 3.5, seems like it should go in the regular branch
14:50:31 <dluch> That sounds logical to me
14:50:34 <rfrasur> alynn26++ GMTA
14:50:37 <abneiman> +1
14:50:43 <jweston> +1
14:51:01 <dluch> okay. I'm going to mark this, so it's in the minutes...
14:51:27 <dluch> #agreed Make docs commits to regular docs branch
14:51:40 <dluch> #info Experimental catalog documentation work
14:51:46 <alynn26> Once the official switch then Commit to Antora docs, as we should migrate the docs at that part to Antora
14:51:55 <Bmagic> that was one of the points in the agenda - make everyone aware that any docs changes from now until Antora is merged - will need to be kept in sync
14:51:56 <dluch> jihpringle said she's working on this. Anyone else
14:51:58 <dluch> ?
14:52:19 <Bmagic> it would be really sweet if doc merges were merged onto both branches
14:52:41 <alynn26> bmagic is there a way to do that?
14:52:46 <Bmagic> hunting down the changes and "backporting" is painful - Dyrcona and I messed with that yesterday
14:53:07 <dluch> +1 to alynn26's question
14:53:27 <Bmagic> There isn't a way to magically connect changes from docs/* to docs-antora/* - the contributer or someone will need to make the same changes to the sister documents in the antora branch
14:53:42 <Bmagic> I linked the commit from Jane where she did exactly that a couple of months ago
14:53:47 <alynn26> ouch
14:53:52 <dluch> So same work in two places?
14:53:54 <abneiman> hm
14:54:14 <Bmagic> Dyrcona and I got close, but no cigar
14:54:54 <abneiman> so the answer to my question is actually docs commits need to go in both places
14:55:08 <dluch> Sounds like it, yes
14:55:18 <abneiman> or else the painful backporting, noted by Bmagic
14:55:29 <Bmagic> There are some cases when (because of Antora) - we've combined a few docs into a single - and the heading levels are different. Tricks Git - the best way is manual
14:56:01 <Bmagic> at least until we merge to master
14:56:13 <Bmagic> would be great if we could do that sooner rather than later
14:56:15 <abneiman> how long will we need to commit in both places? would it make more sense to declare a moritorium on new docs til Anotora is fully running?
14:56:33 <Bmagic> That's the thing - it is fully running
14:56:43 <Bmagic> it's a mirror of the current docs atm
14:56:51 <dluch> And what do we need to do, then, to get it in master?
14:57:30 <Bmagic> I'm not sure really :)  -  some of the things that I put in the agenda is all I could think of
14:57:51 <jweston> sidenote as I need to go to 3:00 mtg -- for Experimental catalog documentation work, jihpringle - I'm happy to help or just review
14:58:04 <jihpringle> we're hoping to have basic docs on it for May 19th and then fill them in as we have time after our upgrade.  We have some libraries very eager to try out the experimental catalogue
14:58:14 <dluch> jweston++
14:58:23 <jihpringle> jweston++
14:58:26 <dluch> jihpringle++
14:58:39 <jweston> jihpringle++ great! I'll follow up with you later
14:58:46 <Bmagic> probably need an action item to explore what really is required to merge to master
14:58:57 <jihpringle> jweston sounds good, thanks!
14:59:16 <dluch> So,
14:59:21 <dluch> #info In order to get this merged to master - should we create some sort of roadmap?
14:59:25 <abneiman> Bmagic: agreed, would be nice to have a clean cutover as opposed to long-term merging in tow places
14:59:30 <abneiman> or two places, even
14:59:47 <Bmagic> I believe we can merge to master anytime - doesn't need tied to a release cycle
15:00:57 <dluch> So, has there been/is there some issue with doing that
15:01:07 <abneiman> Bmagic: so, just the standard process? pullrequest, a couple signoffs, committer merge?
15:01:53 <Bmagic> I believe so, yes
15:02:39 <dluch> Can we make that happen?
15:03:16 <Bmagic> the output of the Antora docs are online (linked above) - for anyone to test, for a sign off
15:04:00 <dluch> So, do we have a pullreequest already?
15:04:04 <Bmagic> There are two seperate sets of concerns: merging this branch to master, setting up the new documentation to a server. I don't think they need to be closely linked
15:04:09 <dluch> Just need testing and signoff?
15:04:26 <Bmagic> seperate/separate
15:05:23 <dluch> But we have the new docs server...did we not put Antora stuff there?
15:05:54 <Bmagic> that's the way it is - but it has not been linked officially on the Evergreen page
15:06:30 <Bmagic> I think we are aiming to take this URL: http://docs.evergreen-ils.org/
15:06:37 <dluch> So, can we make that happen?
15:06:51 <Bmagic> I think it's a different topic alltogether
15:08:16 <dluch> Okay, we're over time now, so I'm going to move on, unless anyone has action items they want to add for this
15:08:30 <abneiman> I think we need someone from GPLS to do the URL change
15:09:26 <Bmagic> I'll reach out
15:09:43 <dluch> bmagic++
15:09:56 <dluch> #topic New Business
15:10:05 <dluch> #info Evergreen International Online Conference plans!
15:10:12 <dluch> This is really more informational
15:10:24 <dluch> As you have (hopefully) seen, the Evergreen Conference has been rescheduled as an online conference for June 9-11 from 12-5 in the afternoons, EDT.
15:10:38 <dluch> In DIG-related sessions, we have:
15:10:47 <dluch> alynn26's AsciiDoc, Let's get started (Wednesday, June 10, 1 p.m.)
15:11:02 <dluch> Bmagic's Antora, Antora, Antora: An Evergreen Documentation Bombshell (Wednesday, June 10, 2 p.m.)
15:11:13 <dluch> [Schedule subject to change]
15:11:24 <dluch> alynn26++
15:11:24 <dluch> Bmagic++
15:11:35 <dluch> Any I missed?
15:11:42 <jihpringle> dluch: eastern time?
15:11:47 <dluch> abneiman, anything else you want to talk about related to the conference?
15:11:53 <rfrasur> jihpringle, yes
15:11:53 <dluch> jihpringle: Yes
15:12:01 <jihpringle> thanks :)
15:12:22 <abneiman> dluch: nope, lots of thanks to our presenters and sponsors and Outreach/Conference Committees! I'm so happy we're going to get to have some kind of event.
15:12:33 <dluch> Yes!!
15:12:38 <dluch> abneiman++
15:12:38 <dluch> outreachcommittee++
15:12:38 <dluch> otherconferenceplanners++
15:12:54 <dluch> #info June Meeting
15:13:02 <dluch> I was thinking we would hold the June meeting during our regular time, June 4. Would anyone prefer to hold it the following week, during the conference?
15:13:05 <jihpringle> abneiman++
15:13:15 <abneiman> keep an eye on the website for more info: https://evergreen-ils.org/conference/2020-evergreen-international-online-conference/
15:13:34 <abneiman> I'd prefer June 4
15:13:43 <alynn26> June 4 +1
15:14:08 <dluch> Awesome, thanks!
15:14:10 <dluch> Is there any other new business we need to discuss?
15:15:09 <dluch> Hearing none, next meeting will be June 4. Same bat time, same bat channel.  It will be primarily collaboration time. But probably Antora, too.
15:15:21 <dluch> Thanks for coming, everyone! Sorry to go long!
15:15:29 <dluch> #endmeeting