14:00:12 #startmeeting 2022-01-06 - Documentation Interest Group Meeting 14:00:12 Meeting started Thu Jan 6 14:00:12 2022 US/Eastern. The chair is dluch. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:00:12 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 14:00:12 The meeting name has been set to '2022_01_06___documentation_interest_group_meeting' 14:00:20 #topic Agenda 14:00:31 #info The agenda can be found here: https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:dig_meetings:20220106-agenda 14:00:37 #info alynn26 is Lynn Floyd, Evergreen Indiana 14:00:43 Welcome everyone! Today's meeting will be business, followed by collaboration and working on documentation, if there's time. 14:00:52 #info Bmagic = Blake GH, MOBIUS 14:00:53 #topic Introductions 14:00:53 Please paste "#info is , " to identify who you are and what organization, if any, you represent. 14:00:53 #info dluch is Debbie Luchenbill, MOBIUS 14:00:56 #info dbs is Dan Scott, Laurentian 14:01:14 #info jihpringle is Jennifer Pringle, BC Libraries Cooperative (Sitka) 14:01:38 #info abneiman is Andrea Buntz Neiman, Equinox 14:01:52 #info jweston is Jennifer Weston, Equinox 14:03:28 Thank you all for coming! My apologies again for not getting a meeting reminder out. If you come in later, feel free to introduce yourself when you arrive. 14:03:43 #topic Helpful Information: Documentation contributions and collaboration 14:03:44 #info You can find the Documentation Needs List at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:documentation_needs 14:03:44 #info DIG Roles can be found at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:digparticipants 14:03:57 #topic Old and Ongoing Business 14:03:57 #info Check-in - Happy New Year! How's everyone doing? 14:04:30 Doing good since everything has settled to a point after the upgrade. 14:04:52 alynn26 that's good! 14:04:57 Missing y'all 14:05:10 we miss you too, dbs 14:05:23 * abneiman waves wildly at dbs 14:05:54 and happy new year to all, we had a surprise snowstorm in MD so that was the highlight of my week 14:06:19 Oh, that's right! 14:06:25 abneiman, my brother lives near you, and his kids are loving it. 14:06:59 alynn26: we're supposed to get more tonight! 14:07:26 we were supposed to get some here, but it split below and above us. 14:07:34 We were supposed to get (a tiny bit of) snow last night/this morning, but got nothin'. It all went south. To MD, apparently. :-D 14:07:39 ❤❤ 14:07:46 yes, happy new year! surprise snow here in NC this week, too -- gone in a day (beautiful) -- maybe more tomorrow 14:08:28 Anyone have a solution for this off the top of their heads? ejabberd max_stanza_size = 2000000 and the MARC file in question is only 21KB, so I've ruled that out 14:09:11 well the snow hasn't been a surprise here, but we've had a bit more than usual - we've had about 6 feet since mid December and it's still snowing 14:09:17 abowling: We're having a DIG meeting right now, but I'm sure someone can help after! 14:09:35 dluch: oops sorry 14:09:35 DANG, jihpringle! 14:09:47 jihpringle wins the snow category! 14:09:48 we've got another 9 inches predicted tonight 14:09:50 abowling: no worries! 14:10:43 #info Previous Action Items 14:10:43 How are these coming? 14:10:43 I'll take them in order... 14:11:03 1. 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.8 context. 14:11:20 I have still done nothing. I'm sorry, jweston! 14:11:43 so, jweston (talking in 3rd prson) has done nothing on her list -- sorry! this month looks promising 14:12:09 For me, too (I think)! 14:12:37 #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.8 context. 14:12:54 2. dluch and jweston (and whoever else wants to) will see what documentation is missing from the Documentation Needs List for newest releases. 14:13:07 Also nothing here from me. 14:13:54 same 14:13:58 #action dluch and jweston (and whoever else wants to) will see what documentation is missing from the Documentation Needs List for newest releases. 14:14:16 3. alynn26 and Bmagic will investigate some possible options for adding pdf generating to our documentation site 14:14:28 Have you all had a chance to do this at all? 14:14:45 I did research some of the pdf generation, and there is a antora bug about it. 14:15:25 https://gitlab.com/antora/antora/-/issues/349 14:15:46 I remember you saying that, actually. Was I supposed to remove that action item after last time, lol? 14:15:50 no progress from me on that 14:16:11 It is also in the road map for v 3.0 14:16:16 * dluch is super-with it today 14:16:35 It's ok, it just after the holidays 14:16:42 Hmm, Antora v3.0 was released just a few weeks back 14:17:26 Oh! I assume it wasn't included in 3.0, after all? 14:18:31 So, alynn26 and Bmagic, shall we keep the action item, or no? 14:18:40 looks like no - it's "Unstarted" for milestone 2: https://gitlab.com/antora/antora/-/milestones/21#tab-issues 14:18:45 Well, there is a gitlab plug in that will do it. 14:19:03 keep it. I'm seeing people out there making use of what code does exist. There is an antora-pdf extension 14:19:19 Alrighty... 14:19:23 #action alynn26 and Bmagic will investigate some possible options for adding pdf generating to our documentation site 14:19:42 4. 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:19:49 alynn26, how's this going? 14:19:56 I suppose it begs the question: do we still need* a PDF of our docs? 14:20:03 * alynn26 has not done that one. 14:20:13 Bmagic: yes, we do 14:20:30 #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:20:49 5. dluch will get the October recording processed and posted. 14:21:02 I am personally anti-PDF-for-Docs but it has been requested by some community members, so if there's a way to do it we should try to get that accomplished 14:21:20 pdf -- 14:21:24 Um...I don't think I did this, but don't remember 14:21:30 abneiman: Same 14:22:18 #action dluch will get the October recording processed and posted--unless she already did. 14:22:22 alynn26: The heading font sizes are controlled by our custom CSS repo https://git.evergreen-ils.org/?p=eg-antora.git;a=blob;f=src/css/doc.css;h=5ecfd53b6f6ce33c99a546d29888fa22ccf7dada;hb=HEAD 14:23:42 Bmagic, I know, the issue is it's not using them correctly I think . or something like that. It's may just be a simple edit needs done. 14:24:30 yup, that's it 14:24:40 dbs might make that absolete though :) 14:24:52 6. DIG (and anyone else) will review, comment on, and/or sign off on the patch for https://bugs.launchpad.net/evergreen/+bug/1944205 14:24:53 Launchpad bug 1944205 in Evergreen "Docs: Authority needs more advanced documentation" [Undecided,Confirmed] 14:25:09 I signed off on that one. 14:25:14 alynn26 signed off on the bug--does there need to be more done? 14:25:29 lol. Thank you, alynn26! 14:25:39 I don't think so - I was going to review and push since alynn26 signed off 14:25:42 alynn26++ 14:25:52 alynn26++ 14:25:57 abneiman++ 14:26:49 #info December Zoom Meeting--Recap and Decisions 14:26:58 We had a really nice social time, talked a lot about British mystery shows--and also discussed some docs organization stuff. 14:26:58 (that is, once I remind my holiday brain how to do such a thing as "review and push" lol) 14:27:07 lol 14:27:22 Anyone else want to add anything about December's gathering? 14:28:09 I was an enjoyable time outside for me. 14:28:25 we talked about Cowboy Bebop, too, and now I hope that the (currently rare & expensive) manga might be reprinted! 14:28:35 so sorry I missed it! 14:28:39 Bmagic: hmm, maybe? Headings look okay-ish at https://evergreen-library-system.gitlab.io/evergreen-library-system/docs/latest/opac/using_the_public_access_catalog.html 14:28:49 dluch: we skipped the last action item (#7) --- can you add that as another continuing action item? (oh, and jihpringle, I volunteered you for that one) 14:29:01 Oh, yes! I forgot about Cowboy Bebop! 14:29:29 jweston: happy to be volunteered :) 14:29:31 jweston: Sorry! Yes! 14:29:42 #action jweston will talk to jihpringle and mantis about the documentation an images review spreadsheets, create a Google doc for drafting a contribution guide, and send the link to the docs mailing list for everyone to help. 14:30:08 #info Docs organization: Progress 14:30:14 Seems like this should probably be punted to a future meeting. Anyone have something to discuss today? 14:30:36 +1 punting 14:30:40 +1 14:30:59 cool 14:30:59 +1 14:31:02 That's all I have for old or ongoing business to discuss. Anything I missed that someone would like to talk about? 14:31:44 Is anyone interested in discussing GitLab Pages/CI or GitHub Actions (and/or Antora 3.0)? 14:31:48 #topic New Business 14:31:51 #info Docs auto-generating via Gitlab idea from dbs (http://list.evergreen-ils.org/pipermail/evergreen-general/2021-December/000929.html and thread). 14:31:53 lol 14:31:54 me 14:31:58 me 14:32:31 dbs: you want to lead off? 14:32:51 (I switched the order of new business items, btw) 14:33:06 So first up: correction to my most recent post. 14:33:37 You can download the full set of documentation from every commit / branch in GitLab Pages 14:33:57 (nothing needs to be figured out, other than my overtired brain) 14:34:38 Second: in 3.0 best practice is still to keep a separate git repo for the base Antora build stuff. So I would revert that 14:36:01 Third: working in GitLab or GitHub these days feels like lightyears ahead of CLI-based git workflows, given integrated issue tracking, project planning, Web IDE for drive-by contributions, merge request reviewing, etc 14:36:41 but that one is way outside of the scope of "making it easier to build and test docs" and a much bigger discussion 14:36:43 I actually like working in GitHub better than the CLI. :) 14:37:54 do we need to migrate the Evergreen repository to a gitlab server in order to get this? We've talked about it as a replacement for Launchpad in a different dev discussion a couple of years ago (probably more because you have to skip the pandemic year(s)) 14:37:54 I definitely prefer a GUI also, but I've gotten accustomed to operating within the CLI to the point where I'd need a github refresher to do the same work there 14:38:24 A better way to build and test docs that is more intuitive is better. 14:39:37 Bmagic: hmm - I'm mirroring the git repo on GitLab (have been since it was on gitorious like ten years ago). I don't think a mirrored branch triggers a GitLab CI/CD thing but I can check 14:40:18 alynn26: hard agree about streamlining build/test of docs - it's a major roadblock right now 14:40:45 it might be possible to trigger a rebuild using something like a particular branch name, like docs-build or something hacky... make that a to-do for me 14:41:44 Sure 14:41:45 FWIW, we run gitlab at CW MARS mainly just to try it out. We don't do any fancy CI/CD stuff though. 14:41:55 Having our about-to-be submitted docs reviewed and integrated into the Evergreen Docs look and feel would be super tasty. The routine would be to submit your test changes to a certain pre-defined Git branch, and poof, a minute later, it's rendered on a page somewhere 14:41:59 alynn26 abneiman: even the small win of "can't merge this because you introduced an error" with a clear error message in the branch discussion is so nice 14:42:28 #action dbs will see if it's possible to trigger a rebuild using something like a particular branch name, like docs-build or something hacky 14:42:33 Clear error messages would be a win for me. 14:42:34 :) 14:43:15 dbs++ 14:43:24 dbs++ # indeed 14:43:30 dbs++ 14:43:50 dbs: antora rocks? right? 14:44:04 awww, you're all so sweet 😢 14:45:22 dbs++ 14:46:38 stepped away and just reading up, this sounds promising! 14:46:40 dbs++ 14:47:46 Anything else about this that we need to talk about today? 14:49:16 #info February Zoom Meeting--Show and Tell Topic? 14:49:28 Any requests/volunteers/thoughts about February's topic? 14:50:25 if there isn't anything more technical, how about looking at the doc/images review spreadsheets to jumpstart that initiative? 14:50:46 jweston: that sounds like a good idea 14:50:58 +1, good call jweston 14:51:19 oops -- only I can't make Feb mtg (schedule conflict) -- but hey, I'll support the planning! 14:51:25 lol 14:52:52 #agreed The February Zoom meeting will be looking together at the docs and images review spreadsheets 14:53:05 Is there any other new business we need to discuss? 14:54:15 We are very close to time, so I'm going to call it. But feel free to collaborate! :-) 14:54:25 #info Our next meeting will be on February 3, on Zoom. I'll post the link on the agenda about a week prior to the meeting. 14:54:26 dluch++ 14:54:28 Looks good for me. 14:54:32 dluch++ 14:54:36 Thanks for being here, everyone! 14:54:46 #endmeeting