14:00:08 <dluch> #startmeeting 2020-10-01 - Documentation Interest Group Meeting
14:00:08 <pinesol> Meeting started Thu Oct  1 14:00:08 2020 US/Eastern.  The chair is dluch. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:00:08 <pinesol> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:00:08 <pinesol> The meeting name has been set to '2020_10_01___documentation_interest_group_meeting'
14:00:21 <dluch> #topic Agenda
14:00:35 <dluch> #info The agenda can be found here:  https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:dig_meetings:20201001-agenda
14:00:48 <dluch> Welcome everyone!  Today's meeting will be a little bit of discussion but will mostly be time for collaboration and working on documentation.
14:00:58 <dluch> #topic Introductions
14:01:09 <dluch> Please paste "#info <username> is <name>, <affiliation>" to identify who you are and what organization, if any, you represent.
14:01:09 <dluch> #info dluch is Debbie Luchenbill, MOBIUS
14:01:44 <jweston> #info jweston is Jennifer Weston, Equinox
14:04:41 <abneiman> #info abneiman is Andrea Buntz Neiman, Equinox, apologies for tardiness
14:04:54 <dluch> No worries.
14:05:13 <dluch> It's going to be a pretty fast meeting if it's just the three of us!
14:05:32 <dluch> #topic Helpful Information: Documentation contributions and collaboration
14:05:32 <dluch> #info You can find the Documentation Needs List at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:documentation_needs
14:05:32 <dluch> #info DIG Roles can be found at https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:digparticipants
14:05:48 <jweston> dluch: the power of 3 is with us
14:05:56 <dluch> We are going to do some quick business items...
14:05:56 <dluch> #topic Business
14:06:02 <dluch> jweston: for sure! :-)
14:06:28 <dluch> #info Check-in
14:06:28 <dluch> How is everyone doing?
14:06:28 <dluch> How are things where you are?
14:06:54 <dluch> Have you all had more effects from the tropical storms etc?
14:07:16 <jweston> nothing extreme-weather like to report so that's good
14:07:22 <abneiman> The local health department just shut down a Christian School for concealing COVID cases, so, that's .... special. Otherwise OK.
14:07:35 <dluch> jweston: that is good
14:07:49 <dluch> abneiman: WOW.
14:07:57 <abneiman> right?
14:08:00 <dluch> Glad other things are okay, though.
14:08:03 <abneiman> how are things where you are dluch?
14:09:22 <dluch> Doing okay here, too. Weather is turning gorgeous - October is the best! Still working at home, and presently quarentined with my husband (though I'm almost positive we have colds and not COVID)
14:10:02 <abneiman> :( I hope so!
14:10:54 <dluch> Thanks! He's the one with the cough, and neither of us has fevers, but his doctor wanted us to wait until Saturday to be tested (??)
14:11:16 <dluch> *shurugs*
14:11:31 <jweston> dluch: hoping your colds, and waiting to get tested, are all over soon so you can enjoy the beautiful October
14:11:50 <dluch> Thank you! Me, too! :-)
14:11:56 <dluch> #info Evergreen Hack-a-Way, Oct. 26-28
14:12:12 <dluch> At the last DIG meeting, we decided that we would focus on 3.6 documentation at the Hack-a-Way.
14:12:19 <dluch> I assume you both are attending?
14:12:27 <abneiman> yes!
14:12:29 <jweston> I'll be there
14:12:42 <dluch> Me, too!
14:12:59 <dluch> For anyone looking at the logs later: Of course, you can work on 3.6 (or any other) documentation even if you aren't participating in the Hack-a-Way
14:13:12 <dluch> But we hope you are. :-)
14:13:24 <jweston> was just at hack-a-way planning earlier -- do we want any specific "presentation" time or just open room sessions for drop in work
14:13:25 <dluch> #info We will catch up on most action items and other business at the next DIG meeting
14:13:46 <dluch> Oh, good question.
14:14:34 <dluch> I think just open room sessions. Unless we think we should present about Antora again?
14:15:19 <dluch> (or will this fall under what you're going to talk about in a minute, abneiman?)
14:15:21 <abneiman> It might not hurt to do a quick crash course about the changes that docs writers will need to incorporate due to Antora
14:15:40 <abneiman> there's not many but there are a couple gotchas, and the file tree is different
14:15:42 <dluch> Sounds fine
14:15:51 <jweston> +1 to scheduling quick crash course
14:16:17 <abneiman> which, I still need to update the wiki on that stuff like I said I would so if you want to toss me an action item for accountability's sake, I will take that :)
14:16:57 <dluch> Is that something one of us (aka, one of you) wants to do, or should I ask Bmagic or gcharlton?
14:17:18 <dluch> #action abneiman will update the wiki with new Antora info
14:17:22 <dluch> :-)
14:17:32 <abneiman> I think a dynamic duo of a DIG person plus a tech person would be good
14:17:41 <jweston> agreed
14:17:52 <abneiman> IMO Bmagic makes more sense since he's been heavily invovled with it but I"m not going to voluntell him :)
14:17:59 <dluch> Sounds good to me!
14:18:22 <dluch> Eh, I'll voluntell him. But also ask. ;-)
14:18:24 <jweston> Bmagic did suggest Antora docs as a hack-a-way agenda item, so we can consider he already volunteered :)
14:18:34 <abneiman> dluch++
14:18:35 <dluch> Oh, excellent
14:18:51 <jweston> never hurts to remind him
14:18:56 <abneiman> I think for hackaway focusing on the practicalities is probably best
14:19:18 <dluch> The "hows" for working in Antora?
14:19:22 <abneiman> like, the headings changes; xref changes; directory moves; etc
14:19:28 <abneiman> yeah
14:19:36 <dluch> Yes, I agree
14:19:45 <abneiman> just, "things you as a writer of docs should know"
14:19:56 <abneiman> it's not VERY different but it's different enough
14:19:59 <jweston> +1 to focusing on practicalities
14:20:06 <dluch> Yep.
14:20:23 <dluch> So, abneiman, would you like to be the DIG person?
14:20:42 <abneiman> sure, clearly I'm already up to my elbows in it :)
14:21:01 <jweston> abneiman++
14:21:02 <dluch> Lol. That's what I thought. :-D But I wanted to give you the option.
14:21:06 <dluch> abneiman++
14:21:44 <dluch> Good! So we're all set for the Hack-a-Way, unless there's anything else?
14:21:50 <abneiman> I'll probably pick sandbergja 's brain a little bit as well. IIRC she was planning to attend hackaway as well.
14:21:54 <jweston> I can update the planning committee if you would like
14:22:02 <dluch> Sweet. Thank you both.
14:22:04 <abneiman> jweston++
14:22:12 <dluch> abneiman++ jweston++
14:22:38 <dluch> Okay, so, sliding right into
14:22:48 <dluch> #info Antora update
14:22:52 <dluch> abneiman: What do you have for us?
14:23:37 <abneiman> #info on 9/8/20 gmcharlt merged Bmagic 's Antora branch to master
14:24:04 <rfrasur> #info rfrasur is Ruth Frasur, Indiana
14:24:08 <rfrasur> reading backward
14:24:22 <abneiman> #info in a day or so gmcharlt will update the main docs page to point to the new files
14:25:08 <rfrasur> abneiman, the wiki docs page?
14:25:15 <abneiman> so, we are live & rolling with Antora; and as promised, I dumped a whole pile of new docs into the repo that I had been hanging on to :) so, yay new chapter for DIG! gmcharlt++ Bmagic++ everyone_else++
14:25:18 <abneiman> that's my update
14:25:33 <dluch> Woohoo!
14:25:40 <abneiman> rfrasur: the Docs homepage - https://eg-docs.georgialibraries.org/
14:25:55 <jweston> Hooray!
14:25:55 <dluch> abneiman++
14:26:07 <jweston> abneiman++
14:26:25 <rfrasur> Okay, and I'm sorry to ask stuff that's likely been covered.  Is that going to include docs for 3.3, 3.4 and 3.5?
14:26:29 <dluch> gmcharlt++ Bmagic++ remingtron++ everyone_else++ indeed!
14:27:08 <dluch> Nope. We decided not to backport.
14:27:14 <abneiman> rfrasur: just 3.6 and forward; Jane, Debbie, and I met and agreed that the burden of backporting was too onerous
14:27:38 <rfrasur> Okay.  Fair.
14:27:39 <dluch> Yes, what abneiman said. :-)
14:28:22 <dluch> rfrasur: other questions?
14:28:28 <rfrasur> Nope
14:28:33 <rfrasur> Thanks
14:29:10 <dluch> Great!
14:29:12 <dluch> #info DIG report at Devs meeting
14:29:24 <dluch> Several meetings ago, csharp said he'd add a recurring spot for a documentation update on the Devs meeting agenda.
14:29:36 <dluch> After some Antora confusion, we were feeling like we needed to keep them in the loop better about what DIG was working on.
14:29:57 <dluch> I completely forgot about it, but saw the placeholder for us on the agenda for next Tuesday's meeting.
14:30:13 <dluch> What are the most important DIG things to report about?
14:30:40 <dluch> Antora, 3.6, experimental/not experimental anymore catalog docs?
14:30:43 <abneiman> dluch: I think the backporting decision should be communicated
14:30:47 <dluch> Just Antora?
14:30:53 <jweston> everything Antora-related abneiman just said
14:30:53 <dluch> abneiman: Good idea
14:31:17 <dluch> jweston: also sounds good
14:31:25 <abneiman> dluch: and also just a recommendation that if they write new features and have docs for them, we will happily take those and adocify them and commit them :)
14:31:45 <jihpringle> #info jihpringle is Jennifer Pringle, BC Libraries Cooperative (Sitka)
14:32:01 <abneiman> recommendation-slash-request
14:32:52 <dluch> abneiman: lol. Sounds good, too.
14:32:59 <dluch> Hi, jihpringle!
14:33:20 <jihpringle> hi all, apologies for the lateness I got double booked
14:33:31 <dluch> No worries
14:33:59 <jweston> +1 to recommending/requesting new feature docs and happily responding
14:34:24 <dluch> I am happy to give the update, but would anyone else like to volunteer? I'm also happy to let someone else, if you're excited about it. :-)
14:34:57 <jweston> dluch++ you'll be great!
14:35:07 <abneiman> dluch++ definitely
14:36:01 <dluch> Okay, so all the Antora stuff abneiman mentioned, the no backporting decision, and recommendation-slash-request to give us docs they have for new features they've written
14:36:24 <dluch> Did I miss anything?
14:36:35 <abneiman> sounds good
14:36:37 <jweston> and we'll be at hack-a-way
14:36:56 <dluch> Yes. hack-a-way! Got it
14:37:12 <dluch> Okay!
14:37:14 <dluch> #info Anything else pressing?
14:37:49 <dluch> Thanks, everyone!
14:37:57 <dluch> Today's meeting is intended to be for collaboration/working time, so let's move on to that!
14:38:09 <dluch> (Even though we only have 20 minutes left, lol)
14:38:18 <dluch> #topic Collaboration time
14:38:35 <dluch> What is everyone planning to work on today?  Please let us know here, and feel free to talk and work with each other.  If you'd like extra accountability, I can make an action item to show up in the minutes, but it's not necessary.
14:39:19 <dluch> I put a list of ideas on the agenda, but I assume everyone that's here today probably knows stuff they want to work on.
14:39:42 <abneiman> So, when gmcharlt did a build test with my giant-pile-o-docs, the build generated some errors in a couple adocs. I was going to look at those, but I was hoping there is someone here who can help me better understand "callout" syntax in adoc, because that's where several of the issues are.
14:40:06 <abneiman> *errors in existing adocs, not errors in my new adocs (phew)
14:40:55 <abneiman> anyway, I'm not familiar with the callout syntax and how it's supposed to work
14:41:05 <dluch> Hmm, I'm not either
14:41:34 <abneiman> and asciidoc cheat sheet has let me down for once :*( so I figured before I did deeper Googling, I would ask if anyone here has used that
14:42:52 <jweston> I'm no help there but hooray for abneiman++ generating pile-o-docs
14:43:02 <abneiman> It looks like it's used in docs code blocks - you have a block of code, and use <!-- <1> --> as a comment line, and then after the code block, there's a list: 1. Here's where you put XYZ
14:43:28 <abneiman> anyway it looks normal (to me) on the Antora-generated pages so I'm not sure why it threw an error
14:43:34 <dluch> I asked Bmagic to come see.
14:43:44 <Bmagic> sorry, wasn't looking at this window
14:43:49 * Bmagic reads up
14:44:18 <abneiman> the specific error is "asciidoctor: WARNING: receipt_template_editor.adoc: line 208: no callout found for <1>"
14:44:37 <abneiman> which refers to this: https://eg-docs.georgialibraries.org/prod/docs/latest/admin/receipt_template_editor.html#_subtotals
14:45:11 <abneiman> line 208 specifically is "<1> This line sets the variable."
14:46:39 <Bmagic> when did you get the error?
14:47:06 <abneiman> build test
14:48:08 <Bmagic> the error would have occured in the old docs (because the error is not from antora, but from asciidoctor)
14:48:18 <abneiman> yeah
14:48:33 <abneiman> but I was just going to fix the file, if anyone knew how to fix it
14:48:36 <Bmagic> The build throws lots* of those types of issues during build
14:48:47 <abneiman> since it doesn't actually BREAK anything it's not a big deal, just housekeeping
14:48:52 <Bmagic> I see, well, it's probably going to be a bit of trial and error
14:49:10 <abneiman> oh well in that case I may just let it lie, since, again, no breaking
14:49:11 * Bmagic opening the source adoc file
14:49:33 <Bmagic> I agree, it would be really nice if those errors were taken care of
14:49:47 <abneiman> but! If anyone has any brilliant ideas about that please let me know. The other errors are pretty clear with clear fixes so I'll work on those
14:50:46 <abneiman> though, while you're here Bmagic, I have another docs question for you - how often does the docs site rebuild from master?
14:51:04 <Bmagic> as far as I know, it's not automated
14:51:09 <abneiman> ah
14:51:26 <Bmagic> in fact, last I checked, the antora doc's weren't linked anywhere official
14:51:30 <jeff> First thing I'd try is to give the source block a syntax. The <!-- <1> --> isn't being recognized as a callout. I you prefixed [source,html] or something before the code block it might recognize it.
14:51:30 <abneiman> so what would be the process there? CAN it be automated?
14:51:40 <abneiman> jeff++ I will try that
14:51:57 <abneiman> Bmagic no, they are not linked anywhere Official yet, but they're getting ready to be
14:52:06 <dluch> Bmagic: that's coming very soon (see abneiman's report above)
14:52:11 <Bmagic> jeff: yep, that's what I was thinking... but I wanted to know what sort of "source" was preceeding the block
14:52:41 <Bmagic> in that case, should we use a different published link other than https://eg-docs.georgialibraries.org/prod/ ?
14:53:24 <Bmagic> We can roll with the "prod" for "production" docs, leaving us room for "/dev" or whatever if we want to stage some doc experiments
14:53:57 <abneiman> Bmagic my understanding was that the docs.evergreen-ils.org URL was going to be updated to point at whta is now living on eg-docs?
14:55:06 <dluch> That's what I thought, too
14:55:36 <Bmagic> ditching what we see here now:  https://eg-docs.georgialibraries.org/ ?
14:57:20 <Bmagic> The links on the main website that take the public to: http://docs.evergreen-ils.org/  -> should be updated to https://eg-docs.georgialibraries.org/   .... and then from there, a link to the "current docs" that points to: https://eg-docs.georgialibraries.org/prod
14:57:43 <abneiman_> right, I feel like IRC booted me at the end of last DIG meeting too
14:57:54 <dluch> weird
14:58:26 <abneiman_> anyway, Bmagic, I will double check with gmcharlt but I thought the docs.evergreen-ils.org URL was going to be updated to point to the new Antora-generated docs site
14:58:52 <Bmagic> jeff abneiman: confirmed, the source code for that adoc does not specifically call out any* source for it to interpret. The fix should* be adding this line above the "----" line "[souce,html]"
14:59:15 <abneiman_> jeff++ thanks!
15:00:09 <dluch> We are at time.  Thanks for all the great work!  Feel free to keep going, though.
15:00:23 <dluch> The next meeting will be November 5. Same time, same place. Business meeting first then collaboration time (if there's time).
15:00:38 <dluch> Please continue using the email list and/or Launchpad for questions and other things that come up in between meetings.
15:00:39 <abneiman> dluch++
15:00:46 <dluch> Thanks for coming!
15:00:49 <dluch> #endmeeting