18:01:22 <caroline> #startmeeting Documentation IRC meeting 12 November 2020
18:01:22 <huginn> Meeting started Thu Nov 12 18:01:22 2020 UTC.  The chair is caroline. Information about MeetBot at http://wiki.debian.org/MeetBot.
18:01:22 <huginn> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
18:01:22 <huginn> The meeting name has been set to 'documentation_irc_meeting_12_november_2020'
18:01:31 <caroline> oh boy, it's going to be a long one, lol!
18:01:32 <tcohen> cait I think I found it
18:01:37 <tcohen> oops
18:01:41 <caroline> #link agenda Documentation IRC meeting 12 November 2020
18:01:43 <ashimema> #info Martin Renvoize, PTFS Euope
18:01:50 <caroline> #link agenda https://wiki.koha-community.org/wiki/Documentation_IRC_meeting_12_November_2020
18:02:02 <caroline> #topic Introductions
18:02:09 <caroline> please use "#info" in front of your introduction to have it show up in the automatic minutes
18:02:18 <caroline> #info Caroline Cyr La Rose, inLibro
18:02:24 <lucyvh> #info Lucy Vaux-Harvey, PTFS-Europe
18:02:40 <ashimema> #info Martin Renvoize, PTFS Europe
18:03:13 <caroline> [off] my head's not on straight today, I apologize in advance
18:04:04 <thd> #info, Thomas Dukleth, New York City [A little pre-occupied with sometime employer in hospital]
18:04:24 <caroline> #topic  Review of action points
18:04:47 <caroline> First action point was caroline will write out the current workflow
18:05:03 <caroline> Which has been done, and is available here caroline will write out the current workflow
18:05:18 <caroline> omg... -_-
18:05:19 <caroline> caroline will write out the current workflow
18:05:30 <caroline> link https://wiki.koha-community.org/wiki/Editing_the_Koha_Manual#How_do_Bugzilla.2C_Taiga_and_Gitlab_work_together.3F
18:05:41 <caroline> omg... sorry!
18:05:46 <ashimema> caroline++
18:05:53 <caroline> #link https://wiki.koha-community.org/wiki/Editing_the_Koha_Manual#How_do_Bugzilla.2C_Taiga_and_Gitlab_work_together.3F
18:06:25 <caroline> this was in response to a question by henryb about the workflow and how all the tools work together
18:06:45 <caroline> as we discussed last time, it's not the most optimal workflow, but it's the one we have right now
18:06:54 <lucyvh> Looks great, will be really useful
18:07:17 <caroline> all the other action points were to try to optimize this
18:07:20 <caroline> davidnind will check how we can use gitlab to simplify the workflow
18:07:33 <caroline> david says he's still working on this
18:07:48 <caroline> #action davidnind will check how we can use gitlab to simplify the workflow
18:08:16 <caroline> then I was supposed to check with ashimema on how to work ourselves in the dev workflow on bugzilla
18:08:39 <caroline> which I haven't done despite the reminder by ashimema lol!
18:08:47 <ashimema> so you guys don't use the 'Manual' keyword at all?
18:08:56 <caroline> I've never used it
18:09:06 <caroline> but maybe we should?
18:09:49 <caroline> I though that was your policy of having devs write better docs
18:10:51 <caroline> I'll actionize it again so I don't forget
18:10:55 <ashimema> well.. once upon a time I think it was used to make a bug that needed a manual entry writing still
18:10:58 <caroline> #action  caroline will check with ashimema on how to best insert the docs writing into the dev workflow
18:11:18 <ashimema> whereas the 'Documenatation' component was more about 'bugs with the documentation'
18:12:34 <ashimema> but yeah.. we should work out a workflow for including both parties... making sure there's a smooth transition from 'dev has finished writing the code' to 'someone makes sure theres a corresponding manual update submitted'
18:12:38 <caroline> what is Manual - ByWater and Manual - PTFS-E on the main page?
18:13:09 <ashimema> those are searches I introduced to try and encourage ptfs-e and bywater to write manual entries for the bugs they wrote..
18:13:11 <koha-jenkins> Yippee, build fixed!
18:13:11 <wahanui> Congratulations!
18:13:12 <koha-jenkins> Project Koha_Master_D9 build #1494: FIXED in 52 min: https://jenkins.koha-community.org/job/Koha_Master_D9/1494/
18:13:36 <caroline> are tey based on the Manual keyword?
18:13:44 <ashimema> it filters on who wrote the bug (*@bywater.com or *@ptfs-europe.com) and having the keyword 'Manual'..
18:13:59 <ashimema> then the idea as once they'd submitted a manual merge request they could remove the keyword
18:14:05 <ashimema> yup
18:14:50 <koha-jenkins> Yippee, build fixed!
18:14:50 <wahanui> Congratulations!
18:14:51 <koha-jenkins> Project Koha_Master_U18 build #944: FIXED in 49 min: https://jenkins.koha-community.org/job/Koha_Master_U18/944/
18:15:02 <caroline> When is the best time to add this keyword? like should we have a list of things to go through?
18:15:07 <ashimema> much like the 'release-notes-needed' Keyword is being used at the minute... if it's an enhancement or new feature at push time, the RM adds 'release-notes-needed' and then when we come to work on the release notes we work through all those with that keyword and as we add the release notes text we remove the keyword
18:15:26 <ashimema> well.. I'm not attached to doing it that way.
18:15:33 <ashimema> it just 'a way'
18:15:58 <caroline> yeah but it seems a good way
18:16:27 <caroline> then we could add the manual keyword to the Documentation to-do search
18:16:54 <ashimema> :)
18:17:11 <caroline> We just need to determine when it's best that the docs manager go through and add the keyword
18:17:23 <caroline> I guess I could do it from the release notes as I do it now
18:17:30 <ashimema> the challenge at the moment is that there's loads of bugs marked with the keyword and I'm not sure which ones have already been dealt with
18:17:51 <ashimema> well.. the RM could add the keyword upon pushing the feature
18:18:00 <ashimema> kinda depends when we want the docs to be written
18:18:16 <caroline> but not necessarily every bug needs to go in the manual
18:18:18 <ashimema> I've tried writing them before QA before.. but then QA often results in changes..
18:18:26 <caroline> like back-end stuff, we don't add to the manual
18:18:34 <ashimema> agreed
18:18:52 <ashimema> so it needs a little interaction as to when something needs a manual update
18:19:03 <ashimema> perhaps that could be part of QA?
18:19:19 <caroline> I don't want to add to your load
18:19:24 <ashimema> who makes the call to say "I think this will need an update in the manual"
18:19:53 <caroline> When I go through the release notes to add them to Taiga, I do a first screening
18:20:47 <caroline> and then the writers do a more thorough one when they come upon this particular task
18:20:59 <lucyvh> I think perhaps we only need devs to do this for the bigger features?
18:21:16 <lucyvh> But not sure how to define that?
18:21:37 <caroline> We can ask for help when it's too big
18:21:54 <caroline> ashimema wrote a bunch for the cash management part since he worked so much on it
18:22:18 <lucyvh> Yes, that sort of development definitely
18:22:42 <ashimema> so when do you tend to go through the release notes caroline?
18:22:55 <ashimema> to build your list.. at or just after release?
18:23:15 <caroline> I do it periodically with the commits on gitlab
18:23:27 <caroline> it helps me see only the new stuff that's been pushed
18:24:00 <ashimema> reason I like the idea of adding the keyword at PQA time is that the QA person aught to have a good idea as to whether things have changed enough to warrant a manual entry and it also builds the queue of things to do before the release.. so we might stand a chance of having a manual to release with the release
18:24:05 <ashimema> hope that makes sense
18:24:14 <ashimema> manuals tend to be a few month behind.. at lest
18:24:45 <caroline> yeah that's why I was using the release notes commits to see the pushes as they were pushed
18:25:12 <caroline> (Joubu's suggestion, I need to give credit :) )
18:25:30 <ashimema> coolios
18:25:40 <ashimema> that's a reasonable approach
18:26:07 <ashimema> and means the manual keyword is a bit redundant
18:26:13 <caroline> So I could do the same and instead of adding a Taiga entry, I would just add the manual keyword
18:26:18 <ashimema> taiga would in effect contain the same list
18:26:35 <ashimema> whatever you're most comfortable with
18:26:51 <ashimema> just so long as we're all on the same page :)
18:26:51 <caroline> well, I think the purpose was to mlimit the number of tools we use
18:27:40 <caroline> We can try it like this for the 21.05 release and see if it works better
18:27:47 <ashimema> it's very lightwieght to use bugzilla.. especailly as the release note drafts contain links to bugzilla.. you can quickly click through, add the keyword, then close the tab
18:27:52 <ashimema> that's how I did it as release manager
18:28:31 <caroline> ok so first we have to clean up the manual keyword
18:28:49 <caroline> #action caroline will clean up the manual keywords in bugzilla
18:29:13 <ashimema> I can probably get cait/rangi to do that (that way they can do a mass clean and disable email so we don't spam the life out of people)
18:29:25 <caroline> good idea!
18:29:39 <caroline> #action ashimema will ask cait or rangi to clean up the manual keyword
18:29:54 <cait> oh no, i am missing the meeting, again
18:30:07 <ashimema> were you going to draw a fresh line.. i.e. just remove the keyword as it stands from everything and start fresh for 21.05... I think that's probably the easyest thing to do
18:30:09 <ashimema> haha.
18:30:15 <ashimema> naughty cait ;)
18:30:19 <caroline> #agreed for the 21.05 release we will try using the "manual" keyword instead of Taiga to build up the task list
18:30:20 <cait> are here that many actually?
18:30:26 <ashimema> \i'm just volunteering you for things
18:30:32 <cait> I see
18:30:55 <ashimema> 128 bugs with manual keyword right now cait
18:31:00 <cait> but it's probably not going ot happen before next week
18:31:13 <cait> oh i thought it was only me using it :)
18:31:14 <caroline> no worries, it's for next release
18:31:22 <cait> i could also try and fix them all... hm
18:31:56 <ashimema> we're talking about making it a more official workflow cait :)
18:32:04 <ashimema> making us all a bit more joined up
18:32:21 <cait> sounds good - i meant writing manual patches for the ones i set myself would also be a way to get rid of them :)
18:32:25 <caroline> info new workflow will be to go through release notes and add the Manual keyword where a manual update is needed
18:32:37 <caroline> # info new workflow will be to go through release notes and add the Manual keyword where a manual update is neede
18:32:42 <caroline> #info new workflow will be to go through release notes and add the Manual keyword where a manual update is neede
18:32:47 * cait sends cookies
18:32:54 <caroline> thanks! I need some
18:33:10 <ashimema> what I'd really like to see if submitters taking a bit more responsability for documenting their submissions... doesn't mean the dev has to write the docs (often us devs are terrible at writing docs people can understand)... but they can and should pester their companies to help them write docs
18:33:13 <ashimema> :)
18:33:16 <ashimema> cookies !
18:33:41 <koha-jenkins> Yippee, build fixed!
18:33:41 <wahanui> Congratulations!
18:33:41 <koha-jenkins> Project Koha_Master_D10 build #405: FIXED in 56 min: https://jenkins.koha-community.org/job/Koha_Master_D10/405/
18:33:43 <caroline> Can there be more than one assignee per bug?
18:34:10 <ashimema> afraid not.. though we could add a custom field to bugzilla easily enough
18:34:14 <caroline> I could try to assign bugs to docs writers from compagnies of the dev
18:34:20 <ashimema> for 'docs assignee' perhaps
18:34:28 <caroline> but I think that would be a bit unfair
18:34:59 <caroline> like kelly and lucyvh would end up with everything
18:35:00 <cait> we could propose it
18:35:28 <cait> i still think it might be nice to see if someone has already taken it on
18:36:11 <cait> but a comment could work too until it gets a lot
18:36:36 <ashimema> I can very easily add the custom field.. just checking if I can make it like assignee allowing you to pick a bugzilla user
18:36:39 <caroline> I think we should use the comments until we are happy with the workflow
18:36:44 <caroline> change one thing at a time
18:36:44 <wahanui> caroline: that doesn't look right
18:37:07 <cait> who is supposed to set the new manual keyword after the clean-up?
18:37:18 <cait> can i still use it in qa when i notice something will need docs?
18:37:22 <caroline> I would
18:37:27 <caroline> but yeah  please do
18:37:52 <caroline> It would be the same basic thing I'm doing right now, go through release notes and add where I fell documentation is needed
18:38:19 <caroline> ashimema proposed to do it during qa, but I don't want to transfer this load to you necessarily
18:39:15 <caroline> I want to summarize what we agree on
18:39:24 <caroline> If someone has an objection, please voice it
18:39:51 <caroline> #agreed the manual keyword will replace taiga for the 21.05 release as a test for this workflow
18:40:21 <caroline> #agreed docs manager will go through release notes and add Manual keyword where it is needed
18:40:54 <ashimema> caroline++ #being generally awesome
18:41:21 <caroline> #action change the Documentation to-do search on bz main page to include Documentation component OR manual keyword
18:41:40 * caroline blushes
18:41:53 <cait> there might be bugs (not enh) that warrant changes in the docs - so good to keep an eye out for those maybe
18:41:58 <cait> i qa
18:42:05 <koha-jenkins> Yippee, build fixed!
18:42:05 <wahanui> Congratulations!
18:42:06 <koha-jenkins> Project Koha_Master_D10_Deps build #134: FIXED in 42 min: https://jenkins.koha-community.org/job/Koha_Master_D10_Deps/134/
18:42:36 <caroline> #info anyone can add Manual keyword if they feel it is needed
18:43:13 <koha-jenkins> Project Koha_Master_D10_Deps build #135: FAILURE in 1 min 7 sec: https://jenkins.koha-community.org/job/Koha_Master_D10_Deps/135/
18:43:15 <caroline> #action caroline will document workflow for 21.05
18:43:40 <caroline> anything to add on the topic of workflow optimization?
18:44:43 <caroline> ok moving on...
18:44:51 <caroline> #topic  Project updates
18:45:03 <caroline> anyone has project updates?
18:45:24 <caroline> thd wiki?
18:45:30 <thd> Yes.
18:47:50 <thd> I am arranging to have a special period of doing a job from a friends home in Washington, DC caring for his father for a couple of weeks which should give me some better concentrated isolation of sorts for the wiki.
18:47:51 <talljoy> good day!
18:48:27 <thd> That is likely to be the first two weeks in January.
18:48:52 <caroline> cool!
18:49:19 <caroline> I don't think there are any other updates on projects
18:49:25 <thd> I will not have my mother stopping me from doing things for Koha, because I am not doing any real travelling.
18:49:59 <caroline> #topic  What's been done so far
18:50:22 <caroline> We've had a couple merge requests, so that's good
18:50:30 <caroline> means the manual is being worked on
18:50:50 <caroline> I know I did a bit because it releives stress for me to work on this lol!
18:51:14 <lucyvh> I've managed just a couple - I'm struggling to update systempreferences.rst at the mo!
18:51:27 <caroline> how are you struggling?
18:51:28 <lucyvh> I think the file might be getting too big?
18:51:33 <caroline> oh!
18:51:45 <caroline> maybe we shoudl divide it up?
18:51:50 <lucyvh> It freezes in my browser so can't make updates?
18:52:02 <lucyvh> My just be me :)
18:52:14 <caroline> ok I'll try to divide it more
18:52:20 <caroline> by module
18:52:31 <caroline> I wanted to make smaller chapters anyway
18:53:14 <caroline> #action caroline (or anyone) to divide the syspref file as it is getting too big for updates through gitlab GUI
18:53:27 <lucyvh> It gives you more work - sorry caroline!
18:53:42 <lucyvh> As I say, may just be for me?
18:53:52 <caroline> no worries, like I said it helps me relieve stress :)
18:54:06 <lucyvh> :)
18:54:07 <caroline> I procrastinate by being production on the manual
18:54:08 <ashimema> some chapters are indeed pretty big
18:54:10 <cait> it is our biggest, removing hte Administration bits was a first step, but it might not be enough for editing in the browser
18:54:18 <cait> string wise... prefs are massive
18:54:21 <cait> you can see it on translate
18:54:25 <ashimema> haha.. I know that feeling caroline...
18:54:35 <ashimema> I have a very large 'procrastination list'
18:54:48 <cait> sometimes it's good because it gets other stuff done...
18:54:56 <ashimema> indeed
18:55:42 <caroline> it's something I feel I'm good at so it helps in moments where work is hard
18:56:03 <lucyvh> I just need work to quieten down so I can do more manual stuff
18:57:09 <caroline> #topic  Content development guidelines
18:57:26 <caroline> I had two things I wanted to discuss here, but it's getting late
18:58:03 <caroline> After Julius' talk at Koha con on accessibility, I looked up how to add alt text to images in the manual
18:58:11 <caroline> #linkhttps://wiki.koha-community.org/wiki/ReStructuredText_-_Tips_and_Tricks#Images
18:58:18 <caroline> #link https://wiki.koha-community.org/wiki/ReStructuredText_-_Tips_and_Tricks#Images
18:58:22 <caroline> I put it here
18:58:49 <caroline> so when you add images, please add some descriptive text with it to help people with accessibility issues
18:59:17 <ashimema> cool caroline
18:59:28 <ashimema> I noticed there was a start on that :)
18:59:29 <caroline> #info when adding images, remember to add alt text for increased accessibility
18:59:31 <lucyvh> Will do
18:59:47 <caroline> I'll leavet he other points for next meeting
18:59:57 <caroline> #topic  Next steps
19:00:19 <caroline> priority is to Work on new features and enhancements for 20.11
19:00:45 <caroline> #topic  Set time of next meeting
19:00:48 <thd> Obviously, with or without alt the text of the manual should make things clear.
19:01:29 <caroline> 4 weeks from now is dec 10
19:01:34 <caroline> is that good?
19:01:35 <thd> Trying again:  Obviously, with or without alt text for images, the text of the manual should make things clear.
19:01:45 <caroline> thd indeed
19:02:13 <lucyvh> Dec 10 good for me
19:02:17 <caroline> but if someone with a screen reader is read "image1455" it's not clear if the image adds to the text or not
19:02:41 <caroline> I for one would be curious what "image1455" is...
19:03:29 <caroline> Usually images in the manual just show what that part of Koha looks like, images don't necessarily add to the text, but blind people can't know that
19:03:54 <caroline> so just wirting "add new item type form" at least tells them they aren't missing out on anything important
19:03:57 <caroline> (I think(
19:04:29 <koha-jenkins> Project Koha_Master_U18 build #945: SUCCESS in 49 min: https://jenkins.koha-community.org/job/Koha_Master_U18/945/
19:04:30 <thd> 10 Dec++
19:04:37 <ashimema> yup
19:04:51 <caroline> #info Next meeting: 10 December 2020, 18 UTC
19:04:57 <caroline> #endmeeting