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