14:00:58 <dluch> #startmeeting 2019-11-07 - Documentation Interest Group Meeting
14:00:58 <pinesol> Meeting started Thu Nov  7 14:00:58 2019 US/Eastern.  The chair is dluch. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:00:58 <pinesol> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:00:58 <pinesol> The meeting name has been set to '2019_11_07___documentation_interest_group_meeting'
14:01:10 <dluch> #topic Agenda
14:01:21 <dluch> #info The agenda can be found here:  https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:dig_meetings:20191107-agenda
14:01:31 <dluch> Welcome everyone!  Today's meeting will be business, followed by collaboration and working on documentation.
14:01:41 <dluch> #topic Introductions
14:01:49 <dluch> Please paste "#info <username> is <name>, <affiliation>" to identify who you are and what organization, if any, you represent.
14:01:56 <dluch> #info dluch is Debbie Luchenbill, MOBIUS
14:02:02 <remingtron> #info remingtron is Remington Steed, Hekman Library (Calvin University)
14:02:20 <Bmagic> #info Bmagic is Blake GH, MOBIUS
14:02:23 <jihpringle> #info jihpringle is Jennifer Pringle, BC Libraries Cooperative (Sitka)
14:02:23 <alynn26> #Info alynn26 is Lynn Floyd (Evergreen Indiana)
14:02:25 <abneiman> #info abneiman is Andrea Buntz Neiman, Equinox
14:02:31 <sandbergja> #info sandbergja is Jane Sandberg, Linn-Benton Community College
14:03:01 <jweston> #info jweston is Jennifer Weston, Equinox
14:04:19 <dluch> Thank you all for coming! If you come in later, feel free to introduce yourself when you arrive.
14:04:29 <dluch> Also, before we get started, I have a doctor's appointment I should have canceled but forgot to, so need to leave on the half hour.  If we're still going then (which I assume we will be), will someone volunteer to become the meeting "runner" to finish and close out the meeting?  Please?  (I can email you my "script" outline for the meeting, if you want.)
14:05:22 <abneiman> dluch: I can do that - script would be appreciated tho :)
14:05:42 <dluch> abneiman: Thank you!  I'll get that to you in just a minute!
14:05:45 <dluch> abneiman++
14:05:57 <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:13 <dluch> #info DIG Roles can be found at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:digparticipants
14:06:21 <dluch> #topic Old and Ongoing Business
14:06:31 <dluch> #info Previous Action Items
14:06:38 <dluch> How are we doing on these?  I'll take them in order...
14:06:49 <dluch> #1, adding ideas for simple topics in the Quick Starts section of the wiki (https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:documentation_needs, scroll past the Easy Tasks section).  I see some there.  Anyone added anything recently?  Do we need to keep this as an action item?
14:07:20 <stephengwills> #info stephengwills Maine Balsam Libraries
14:07:34 <sandbergja> I think we don't need to keep it as an action item
14:08:05 <dluch> Cool.  I agree, but didn't want to arbitrarily make that call.  :-)
14:08:26 <dluch> #2, sandbergja: video for proof of concept there?  (I haven't looked recently.)
14:08:33 <sandbergja> haha nope
14:08:36 <alynn26> I do too, getting back  in the swing of things since the Job change,
14:08:46 <sandbergja> can we push that until next time please?
14:08:56 <dluch> sandbergja: Yep!
14:09:04 <dluch> alynn26: what's your new job?
14:09:17 <alynn26> Jason Boyers old job.
14:09:31 <alynn26> at the Indiana State Library
14:09:35 <dluch> #action sandbergja will make a proof of concept for the Quick Starts section
14:09:45 <dluch> Awesome, congratulations!
14:09:49 <alynn26> Thanks
14:10:07 <dluch> #3, jweston or abneiman: Did CWG talk about MARC Edit, right-clicking, and accessibility?  I didn't remember that coming up at the October meeting.
14:10:46 <jweston> We talked about Angular Staff Catalog in October and lots of launchpad bugs -- now combined on cwg wiki so I would say it is covered
14:11:14 <dluch> Okay, so remove the action item?
14:11:20 <jeff> aside: I *think* I just added abneiman as chair of this meeting, so that the dluch -> abneiman handoff should be uneventful.
14:11:22 <abneiman> dluch: we talked about it in the August meeting
14:11:29 <abneiman> jeff++
14:11:32 <dluch> jeff: Thanks!
14:11:34 <dluch> jeff++
14:11:42 <jweston> yes, I think it is fine to remove the action item - thanks
14:11:50 <dluch> jweston++ abneiman++
14:11:52 <abneiman> link: https://docs.google.com/document/d/1DrKYz3N3qDwcGSTWIQ-fV0EVonptphqp2PMQh1QUF0k/edit?usp=sharing
14:12:02 <dluch> Thanks!
14:12:09 <dluch> #4, sandbergja: Did you explore how to and then request abneiman be given docs committing privileges?  Do I remember correctly that actually getting done before the end of the September DIG meeting?
14:12:29 <sandbergja> Yep, abneiman has all sorts of powers now :-D
14:12:30 <jweston> abneiman: ++ thanks for finding it on the cwg notes :)
14:12:37 <dluch> Awesome, thanks!
14:12:41 <dluch> sandbergja++
14:12:54 <dluch> #5, gmcharlt and/or rsoulliere:  How's work coming on moving the docs server?
14:13:02 <abneiman> jweston: np, I knew we HAD discussed it but I couldn't recall when :)
14:13:38 <abneiman> gmcharlt is not available right now but I can follow up with him
14:13:46 <dluch> Okay, thanks.
14:13:49 <dluch> #6, abneiman:  Did you have a chance to look into/plan a community crash course on ascii?
14:13:57 <dluch> (For folks who weren't there, this idea came up in the discussion at the (very brief) October DIG meeting.)
14:14:16 <abneiman> not beyond thinking about it, and getting some feedback to the effect of "Yes, great idea!" LOL
14:14:32 <dluch> :-)
14:14:33 <jweston> +1 still a great idea!
14:14:33 <alynn26> I am thinking of doing my full asciidoc presentation at the Conference.
14:14:44 <dluch> Yep, still +1 to that!
14:14:51 <abneiman> but I do still think it would be valuable, and my November is shaping up to be way less wild than my October so it can stay on my plate
14:15:01 <abneiman> alynn26: that would be great!
14:15:05 <alynn26> Not the Asciidoc in 5 minutes or less
14:15:18 <dluch> #action abneiman will look into/plan a community crash course on ascii
14:15:26 <remingtron> alynn26++
14:15:27 <dluch> alynn26: fantastic!
14:15:33 <dluch> alynn26++
14:15:54 <dluch> Any other old or ongoing business to discuss?
14:15:57 <abneiman> yeah, the "crash course" I was thinking about was mostly "asciidoc in 15 minutes or less" and I will definitely refer people to alynn26's upcoming presentation
14:16:15 <dluch> abneiman++
14:16:46 <alynn26> abneiman: I can share my presentation with you, if you want
14:17:05 <abneiman> alynn26++ thanks! that would be great
14:17:50 <dluch> Okay, moving on..
14:17:58 <dluch> #topic New Business
14:18:10 <dluch> #info Switching to Antora
14:18:24 <dluch> bmagic and remingtron: take it away!
14:18:27 <alynn26> I really like Antora
14:18:31 <Bmagic> :)
14:18:37 <remingtron> we hacked away at the hackaway
14:18:50 <remingtron> and Bmagic has a live demo to show you what we accomplished!
14:18:58 <Bmagic> #info branch is here: https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/blake/LP1848524_antora_ize_docs
14:19:25 <Bmagic> #info the temporary site you can browse RIGHT NOW: http://antora.mobiusconsortium.org/prod/
14:19:40 <Bmagic> This is as far as we got
14:19:56 <remingtron> summary: I think we've answered all the hard questions, but there's plenty of cleanup to do
14:20:04 <Bmagic> The navigation needs to be fleshed out. I went ahead and made the theme "Evergreen-ized"
14:20:22 <remingtron> Bmagic also got the search working, Bmagic++
14:20:22 <Bmagic> I added links in the dropdown menus on the top right
14:20:47 <Bmagic> Right now, since the navigation isn't completed, some pages are only accessible through search
14:21:20 <alynn26> bmagic++
14:21:26 <sandbergja> Bmagic++
14:21:29 <sandbergja> remingtron++
14:21:29 <alynn26> Remingtron++
14:21:33 <Bmagic> aww shucks
14:21:41 <Bmagic> remingtron++
14:21:45 <jweston> bmagic++
14:21:49 <jweston> remingtron++
14:21:56 <remingtron> thanks everybody!
14:22:00 <jihpringle> bmagic++
14:22:01 <jihpringle> remingtron++
14:22:06 <jeff> is it expected that there is no search results page, just an autocomplete-style pop-up of matching titles?
14:22:08 <Bmagic> I got "hooked" on working on it and worked through the airport and in the car up to 2am
14:22:22 <Bmagic> jeff: yep, out of the box
14:22:29 <abneiman> I know this is a WIP but will the pages eventually be more "broken up" by lower-level section?
14:22:30 <jeff> Bmagic++
14:22:42 <Bmagic> info: using antora "lunr" https://github.com/Mogztter/antora-lunr
14:22:45 <dluch> bmagic++
14:22:48 <dluch> remingtron++
14:22:53 <abneiman> see http://antora.mobiusconsortium.org/prod/docs/latest/admin/acquisitions_admin.html vs http://docs.evergreen-ils.org/reorg/3.2/staff_client_admin/_acquisitions_administration.html#_acquisitions_settings
14:23:37 <alynn26> Can we share this with others to get additional opinions?
14:23:47 <Bmagic> I like to do that - compare two pages. Though it's not always apples to apples because our current production documents slice and dice stuff
14:23:56 <alynn26> That page I think is missing the TOC
14:24:22 <Bmagic> alynn26: I think we need a more "permanent" server to stage this stuff - the new server perhaps?
14:24:47 <remingtron> yeah, once gmcharlt has the new docs server ready, we'll setup a more public demo of Antora
14:24:48 <abneiman> right - what I'm asking is that, in Antora, the Acq Admin is one big long page - there's value to some slicing and dicing via lower level section headings, and I want to know if that's in the plan
14:24:53 <dluch> abneiman: I think we'd be able to do that if we wanted to?  bmagic/remingtron?
14:25:01 <dluch> Or is it just all scrolling?
14:25:32 <Bmagic> we spoke briefly about that at the Hack-a-way - we thought the scrolling was better
14:25:45 <remingtron> we can break pages into smaller pages, but that would take some manual work, case by case
14:25:53 <Bmagic> for orgainization/search reasons too
14:26:15 <jihpringle> it's often helpful to be able to send links to specific section
14:26:25 <abneiman> ok. obviously I forgot that from hackaway :) I think in some cases, breaking up reallllly long pages (like Acq Admin) is more user friendly for several reasons
14:26:37 <Bmagic> yep, that page is seriously long
14:26:38 <dluch> I think we'd need some sort of menu, though, linking to sub-sections, otherwise it'll be a pain scrolling through
14:26:44 <dluch> Yes
14:26:47 <remingtron> jihpringle: Antora gives you a section link when you hover a section title
14:26:47 <sandbergja> One question: how close are we keeping to the original antora default UI?  Is there an easy way to bring in improvements made to the default UI into our customized UI?  I ask because there are a few accessibility issues with the original UI, and want to know if an upstream fix would eventually trickle down into the layout you made, Bmagic.
14:26:52 <Bmagic> The TOC at the top would help that page with a one-liner
14:27:18 <abneiman> right. and big +1 to jihpringle's comment about linking to a specific section - whether that's by anchor links or splitting pages, that's an important feature to preseve
14:27:30 <remingtron> yeah, that's one suggestion: add a Table of Contents to top of each page in Antora
14:27:54 <jweston> +1 to TOC
14:28:03 <Bmagic> yep, this line   ":toc:"  added to the top of each page will go a long way
14:28:12 <dluch> cool
14:28:13 <abneiman> +1 to TOC definitely
14:28:27 <abneiman> thanks remingtron++ Bmagic++
14:28:33 <dluch> #chair abneiman
14:28:33 <pinesol> Current chairs: abneiman dluch
14:28:42 <dluch> later, all!
14:28:44 <remingtron> sandbergja: good question. Bmagic, thoughts on how we'd handle UI upgrades?
14:28:44 <Bmagic> dluch++
14:28:49 <jweston> dluch++
14:28:52 <jihpringle> dluch++
14:28:56 <abneiman> dluch++
14:28:58 <remingtron> dluch++
14:29:26 <Bmagic> UI upgrades - git is our friend there
14:29:55 <Bmagic> right now, because we didn't want to "nest" a git repo within a git repo. We hvae the files simply "copied" into the Evergreen repo
14:30:47 <Bmagic> we could keep it outside of the Evergreen repo for ease of merging upstream
14:31:45 <sandbergja> Bmagic: keeping the layout in its own repo might be good!
14:32:10 <Bmagic> I think if we do that (correct me) we can have it "track" the github repo?
14:33:16 <Bmagic> You git experts in the room - there is a way to nest the repo within Evergreen, thereby avoiding adding another root repo? gmcharlt and I spoke briefly and he favored not doing that
14:34:10 <Bmagic> This project actually uses two upstream repos: https://github.com/Mogztter/antora-lunr and https://gitlab.com/antora/antora-ui-default
14:35:23 <abneiman> as noted gmcharlt is unavailable right now, but do one of our other core committers have thoughts about bmagic's proposal?
14:35:46 <sandbergja> I know you can set up git submodules -- https://git-scm.com/book/en/v2/Git-Tools-Submodules -- but I'd defer to others who have worked with those more
14:36:06 <jeff> I'm in agreement with gmcharlt about not adding a git submodule. It looks like based on the Antora docs the UI code is intended to be a distinct git repo.
14:36:08 <Dyrcona> Git submodules can be interesting.
14:36:21 <Dyrcona> Not necessarily in a good way.
14:36:21 <Bmagic> I nested the repos at first. And it caused gitolite to have a heart attack
14:36:30 <csharp> I think the objection was that submodules get really complicated really fast and git is already a hurdle for most
14:36:31 <jeff> (based on a quick skim of https://docs.antora.org/antora/2.2/features/#interchangeable-ui just a few minutes ago)
14:36:39 <Bmagic> It was clear that we needed to introduce some code into the repo to make it play nice with the repo above it
14:36:53 <jeff> "Antora interfaces with a site UI that is stored and managed as a separate project."
14:37:33 <sandbergja> I think it's okay to have part of the build process be "run git clone [URL of ui repo]"
14:37:45 <sandbergja> as long as that build process is really well documented
14:37:56 <csharp> I think a separately cloned git repo with instructions for integration would be best (there were also concerns about licensing conflicts between antora [Mozilla Public License] and EG [GNU GPL v2])
14:38:00 <jeff> I believe that's what Antora expects to do by default -- there's no need to add on something special to make that happen.
14:38:18 <Bmagic> jeff: sandbergja: yep! - I think that's the way forward
14:38:37 <csharp> +1
14:38:42 <Dyrcona> Well, cmake is really good at managing dependencies like that without resorting to git submodules.
14:39:15 <Bmagic> and the lunr repo gets put into the ui repo.... it's like Inception
14:39:30 <sandbergja> I'm curious about how Windows users would contribute to antora-ized docs
14:39:42 <Bmagic> I wouldn't be surprised if the lunr repo get's wrapped into the default UI before too long anyway
14:39:45 * csharp plays the Inception soundtrack whenever Bmagic speaks
14:40:11 <sandbergja> Building antora seems like a lot to ask of casual documentation contributors to test their changes
14:40:23 <Bmagic> sandbergja: contribution hurdles remain the same
14:40:24 <sandbergja> (not that our current stack isn't also a lot to ask)
14:41:00 <Bmagic> I've been recommending folks use ascidocfx https://asciidocfx.com/
14:41:43 <Bmagic> 1. clone the Evergreen repo. 2. Open Asciidocfx. 3. Browse the file system to the document you want to edit. 4. Save the file
14:42:14 <sandbergja> On a related note: in my perfect world, when somebody throws a documentation pull request at the github repo, antora runs on their branch, and generates a preview view of what the documentation looks like with their changes
14:42:20 <Bmagic> If anything, the orgainization that Antora requires might make it *easier* to contribute
14:43:01 <jeff> setting up CI for docs would have benefits beyond just helping Windows users contribute
14:43:23 <sandbergja> Angular does that with docs pull requests, and I was really impressed: https://github.com/angular/angular/pull/31630#issuecomment-512934983
14:43:51 <jeff> There are two options for local preview, as long as you can run antora on your Windows PC: static pages, or run the local server.
14:44:08 <Dyrcona> CI for docs would be a nice start in the general direction of CI.
14:45:10 <abneiman> Bmagic: remingtron: what do you see as next steps here?
14:45:41 <abneiman> and thank you Dyrcona++ csharp++ jeff++ sandbergja++ for committer perspective
14:47:00 <Bmagic> abneiman: I think we need the staging server. Keep hammering out the navigation. Edit all of the headings (with script). Add the TOC. Elicit feedback, Review, and finally publish
14:47:59 <Bmagic> Once it's in master, it will propigate down the version trees, and we get the full advantage of "version" of the docs (shown on the UI in the bottom left corner)
14:48:26 <Bmagic> Starting with 3.5 is a reasonable goal I would say
14:48:32 <abneiman> And DIG members present, are we +1 to moving forward here? (I don't think we really need a formal vote but I can call one if desired)
14:49:32 <jweston> +1 to moving forward
14:49:43 <jihpringle> +1 from me
14:49:43 <stephengwills> +1 Marchon
14:50:04 <sandbergja> +1 from me!
14:51:05 <abneiman> ok - hearing no objections to the general concept, let's toss some action items in
14:51:24 <abneiman> #action abneiman will prod gmcharlt about the test server
14:51:57 <abneiman> Bmagic and remingtron, are you working on the nav? are there others who want to help here?
14:52:25 <Bmagic> I believe there are 70+ links/lines needed
14:52:54 <Bmagic> we could divide and conquer. Anyone who wants to help... can!
14:53:12 <sandbergja> Bmagic: would they just need access to the working repo to be able to help with that task?
14:53:25 <Bmagic> make that 192 lines needed (roughly)
14:54:31 <Bmagic> sandbergja: that's correct - which I don't think there is an issue, it's out there ready for cloning/merging/patching/pushing
14:55:09 <Bmagic> 192 from `ll modules/*/pages/*|wc`
14:55:33 <sandbergja> Is now the right time to set up another git repo for the ui/layouts?
14:55:46 <Bmagic> yep, that'd be great
14:56:15 <abneiman> sandbergja: will you set that repo up?
14:56:15 <sandbergja> I can volunteer to work with gmcharlt and Dyrcona on that
14:56:21 <abneiman> heh
14:56:24 <Bmagic> probably just the one for the UI - not sure about lunr - we don't make changes to that (yet)
14:56:37 <sandbergja> that sounds good!
14:56:53 <abneiman> #action sandbergja gmcharlt and Dyrcona will work on setting up a git repo for ui (and maybe layouts)
14:57:06 <abneiman> #action bmagic, remingtron, and players to be named later will work on the nav, of which there are approx 192 lines needed
14:57:24 <abneiman> anything else for the near term? we're coming up on the hour
14:57:45 <sandbergja> Bmagic: will your demo version be up for a while -- so I can gather some feedback from my colleagues locally?
14:58:02 <Bmagic> yeah but not for long! It's not a machine that should be online
14:58:10 <sandbergja> okay!
14:58:11 <Bmagic> how's end of day today?
14:58:22 <sandbergja> Sure, I can gather some quick feedback by then
14:58:25 <remingtron> ...sorry I stepped away, but I'm back!
14:58:37 <Bmagic> remingtron: lol, I was wondering
14:59:09 <abneiman> ok - any additional business for DIG?
15:00:12 <abneiman> hearing none...
15:00:14 <abneiman> #endmeeting