21:07:27 <caroline> #startmeeting Documentation IRC meeting 2 October 2018 21:07:27 <huginn> Meeting started Tue Oct 2 21:07:27 2018 UTC. The chair is caroline. Information about MeetBot at http://wiki.debian.org/MeetBot. 21:07:27 <huginn> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 21:07:27 <huginn> The meeting name has been set to 'documentation_irc_meeting_2_october_2018' 21:07:43 <caroline> #chair cait 21:07:43 <huginn> Current chairs: cait caroline 21:07:49 <caroline> #chair davidnind 21:07:49 <huginn> Current chairs: cait caroline davidnind 21:07:53 <caroline> mwa hahah! 21:08:19 <caroline> #topic Introductions 21:08:34 <cait> #info Katrin Fischer, BSZ Germany 21:08:36 <caroline> (please use "#info" in front of your introduction to have it show up in the automatic minutes) 21:08:45 <caroline> #info Caroline Cyr La Rose, inLibro 21:08:54 <davidnind> #info David Nind, Wellington, New Zealand 21:09:13 <caroline> Joubu? 21:09:27 <Joubu> #info Jonathan Druart 21:09:30 <caroline> #topic What's been done so far 21:09:56 <caroline> KohaCon18 & hackfest 21:10:07 <caroline> rangi and cait gave a presentation on documenting Koha with a live edit of the manual (!!) 21:10:13 <caroline> #link https://www.youtube.com/watch?v=XXn9k4Ir8is&index=24&list=PLV_OXyJ1D3BgcRtxrjVkCBXjSt7Dr1qKy&t=0s 21:10:19 <caroline> cait++ rangi++ 21:10:25 <caroline> It generated a lot of interest 21:10:27 <davidnind> rangi++ cait++ 21:10:35 <cait> rangi did the demo - he is the brave one 21:10:39 <caroline> I don't know if ppl asked them questions in private afterwards, but I know a couple approached me with questions 21:10:57 <cait> he challenged them to make a edit for a fix of the version number and 2 did 21:11:15 <caroline> Maybe future writers? :D rangi noticed new contributors. 21:11:25 <caroline> during the hackfest, I gave a workshop on editing the manual and there was 8-10 ppl in attendance. 21:11:27 <davidnind> he gave out some chocolate fish as well I think 21:11:37 <davidnind> caroline++ 21:11:55 <caroline> That's a NZ thing, it's not as much an incentive for the rest of us ;) 21:11:58 <cait> caroline++ 21:12:02 <cait> she was awesome :) 21:12:04 <caroline> The wiki page was really useful 21:12:08 <caroline> #link https://wiki.koha-community.org/wiki/Editing_the_Koha_Manual 21:12:20 <caroline> hehe thx :) We all did a great job 21:12:22 <davidnind> I thought it went very well - there was a lot of interest, and I think everyone managed to get something commited 21:13:07 <caroline> Any other comments? 21:13:25 <caroline> moving on 21:13:29 <caroline> #topic Workflows 21:13:53 <caroline> Does anybody have anything to say about this? It's a topic by default so I never know 21:14:18 <cait> i think no changes 21:14:19 <Joubu> (I have to leave sooner than expected, sorry! See you tomorrow) 21:14:22 <cait> so we can probably move on? 21:14:28 <davidnind> Is everyone okay if I add a section on setting up a local copy of Sphinx, so you can generate an updated docs 21:14:28 <caroline> #topic Next steps 21:14:45 <caroline> davidnind: of course! 21:15:02 <davidnind> wasn't as complicated as I thought 21:15:20 <caroline> I'm eager to see it, I didn't know it was possible 21:15:30 <caroline> So you can see in real time your changes? 21:15:45 <davidnind> yep - doesn't take too long to generate 21:15:50 <caroline> Cool! 21:16:07 <davidnind> was easy to setup on Linux, can do on Windows, but don't have a mac to test 21:16:11 <caroline> Please do! I'm always anxious with the syntax because I don't know how it will turn out 21:16:20 <cait> you have to regenerate 21:16:28 <davidnind> added to my task list! 21:16:28 <cait> but it does work :) and you can have your own epub too 21:16:32 <caroline> like the doctor? 21:16:39 <cait> heh 21:16:46 <cait> i so want to say yes to that 21:16:46 <caroline> :) 21:17:09 <caroline> Alrighty 21:17:26 <caroline> #action davidnind will write a section on setting up a local copy of Sphinx, so you can generate an updated docs 21:17:48 <caroline> #topic Automation of screenshots 21:17:57 <caroline> I noticed a lot of screenshots were out of date in the manual 21:18:05 <caroline> I added a dedicated section in Taiga, but it discouraged me a little bit 21:18:09 <caroline> #link https://tree.taiga.io/project/ldjamison-kohadocs-1805/us/586 21:18:25 <caroline> During hackfest, I spoke with Joubu about his tool to take automatic screenshots. He said no one had really sent him comments, so we weren't sure if it was because there was no interest, or because of another reason (too busy, email got lost in pile of emails, etc.) 21:18:35 <caroline> We discussed of the pros and cons and I wrote them down so we could discuss them here 21:18:41 <caroline> #link https://www.evernote.com/shard/s162/sh/03edec69-1fd2-4f30-b562-f12ffc1f9e0b/b4179d876d0fedaa086a35d116a0f44c 21:18:49 <caroline> PROS 21:18:53 <caroline> 1) Screenshots are always up-to-date with the latest version, do it once and they're always there 21:18:57 <caroline> 2) Screenshots can be generated in all languages 21:19:01 <caroline> 3) Script will test all pages, and regressions will be found 21:19:08 <caroline> CONS 21:19:14 <caroline> 1) Harder to add images to the manual, only advanced editors will be able to add them 21:19:19 <caroline> 2) Joubu still has to work on it, he stopped because of the lack of comments 21:19:22 <caroline> 3) Some images might be hard to generate (50% easy, 30% medium, 20% maybe not attainable) 21:20:33 <caroline> Someone wrote on the wiki "Have been experimenting with Selenium+Robot Framework+Screencapture library - looks promising" I'm guessing that's Joubu 21:20:45 <davidnind> That's me - I have been experimenting with Selenium + Robot Framework + Screencapture library 21:20:51 <caroline> ah ok! 21:20:52 <davidnind> forgot to add my name 21:21:05 <davidnind> also ran out of time to add my notes and add repository 21:21:09 <cait> i am not sure i understand how to do it, but it might be easier than i think 21:21:21 <caroline> So what is the workflow for your thing davidnind? 21:21:37 <davidnind> it took me a while to find something useful and relatively easy 21:22:12 <davidnind> Basically, inc plain language you write a script, something like this: 21:22:28 <davidnind> Valid Login 21:22:29 <davidnind> Open Browser To Login Page 21:22:29 <davidnind> Input Username koha 21:22:29 <davidnind> Input Password koha 21:22:29 <davidnind> Capture and crop page screenshot images/login_page.png 21:22:29 <davidnind> ... css=#login 21:22:29 <davidnind> Submit Credentials 21:22:31 <davidnind> Projects Page Should Be Open 21:22:31 <davidnind> [Teardown] Close Browser 21:23:05 <cait> interesting! 21:23:08 <caroline> It looks simple enough 21:23:23 <davidnind> You then run a command from the command line and it folows the steps - can be against any Koha installation (I used the docker testing) 21:23:50 <davidnind> You can take screenshots of parts of pages based on css classes 21:24:02 <caroline> It's very similar to what Joubu showed me. He was working with https://docs.cucumber.io/gherkin/reference/ 21:24:19 <davidnind> You can also add data to fields and capture that before it presses submit 21:24:51 <caroline> davidnind: did you think it was very long to write up everything? 21:24:56 <davidnind> Will have a look at that - I think I did come across cucumber, but thought it was a bit complicated - will check it again 21:25:27 <davidnind> I ran out of time before this meeting, but will add wiki page and repository 21:25:43 <caroline> thank you 21:25:49 <davidnind> It may not cover all screenshots, but maybe most (I hope) 21:26:25 <davidnind> Would take a bit of time to setup existing screenshots, but would make it much easy in the future 21:26:29 <caroline> Personnaly, I think this would be very interesting, especially to have up-to-date screenshots and also screenshots in all languages 21:26:36 * rangi is just heading out 21:26:39 <rangi> but davidnind http://git.koha-community.org/gitweb/?p=kohadocs.git;a=blob;f=README.md;hb=2482c4476c54347e652824ad2ec41e3a37b78c0b 21:26:45 <rangi> we used to have instructions 21:26:58 <rangi> this commit killed them 21:27:00 <rangi> http://git.koha-community.org/gitweb/?p=kohadocs.git;a=commit;h=14e3bbb13fbe0c3d6eae8877fcddd9ff75d41f53 21:27:05 <rangi> would be good to get them back :) 21:27:19 <davidnind> Will have a look, thanks rangi! 21:28:01 <davidnind> For languages you could change the Koha install language and then run 'test' 21:28:57 <davidnind> I'm sure there will be some problems... 21:29:36 <davidnind> Anyway will write up and share, and see if it is viable 21:29:40 <cait> oh oops 21:29:42 <cait> about the docs 21:29:46 <caroline> I think it's still worth a try 21:30:03 <cait> can we add bringing back the readme page? 21:30:10 <davidnind> Looked at a lot of other options, but all seemed to require some sort of programming skills 21:30:43 <caroline> cait what do you mean is there no readme anymore? 21:31:03 <davidnind> the current readme is very brief! 21:31:09 <cait> because rangi just said it got killed 21:31:22 <caroline> I'll add it to taiga 21:31:46 <caroline> #action caroline will add bring back the readme page as a task on taiga 21:31:52 <cait> yeah it's gone: https://gitlab.com/koha-community/koha-manual 21:31:58 <cait> it used to be instructions 21:32:19 <cait> with how to do sphinx, generate locally etc 21:32:23 <caroline> #action davidnind will write up his notes on Selenium+Robot Framework+Screencapture library and share them with the group 21:32:47 <davidnind> the instructions look exactly like what I ended up doing! 21:33:32 <cait> sorry we lost them 21:33:39 <davidnind> the spelling check is useful as well - have to remember to write US english! 21:33:57 <caroline> hehe! 21:34:01 <davidnind> things happen! 21:34:43 <caroline> ready for the next topic? 21:34:57 <davidnind> yep! 21:35:04 <caroline> #topic Organization of images in images.rst 21:35:22 <davidnind> been a bit slack on sending to the list... 21:35:37 <cait> you do so many things 21:35:48 <davidnind> not really! 21:36:05 <davidnind> I procrastinate a lot! 21:36:27 <davidnind> leaning towards the option of organising the index of images using categories by module 21:36:47 <caroline> +1 21:36:53 <davidnind> e.g. cat-0001, circ-0001 21:37:01 <davidnind> and leaving the source images as they are 21:37:40 <davidnind> that way you can hopefully check if there is an image first in that category instead of creating another one 21:37:41 <cait> so not chaging file names/locations, just the numbering? 21:37:42 <cait> ok for me 21:37:56 <caroline> I was thinking 3 capital letters + 3 numbers 21:37:59 <davidnind> there are about 1473 images at the moment 21:38:21 <caroline> phew! 21:38:25 <davidnind> will post to docs list this evening (for me) 21:39:21 <cait> davidnind++ 21:39:22 <caroline> ok so we'll discuss this via email and hopefully agree on a method (I hate hate hate merge conflicts because of images!) 21:39:23 <davidnind> as an aside I used the pngcrush tool and it turned images from about 82.3 MB down to 54.6 MB, about a 1/3rd reduction in size 21:39:47 <davidnind> :) 21:39:49 <caroline> davidnind++ 21:40:55 <davidnind> caroline++ fixing all the docbugs! 21:41:00 <caroline> #action davidnind will write a proposition to organize images to the docs mailing list and we will discuss by email 21:41:30 <caroline> #topic Description of development process 21:41:46 <caroline> It was mentioned on IRC that the development process/version maintenance was not documented. Someone was specifically asking why version 17.11.09 came out after version 18.05.03, which is a reasonable question, I think. 21:41:56 <caroline> I was wondering if we wanted to document the outline of the development process, or is that too technical? 21:42:04 <caroline> There is also the question of placement. Would that be in the introduction? in the FAQ? 21:42:20 <caroline> I noticed there was a brief outline on the community website 21:42:34 <cait> hm there is information on the wiki 21:42:37 <caroline> https://koha-community.org/about/release-schedule/ 21:42:45 <cait> but we might want to have osmething more 21:42:54 <cait> maybe a non-technical descriptoin with links to wiki for more? 21:43:20 <davidnind> Perhaps in an appendix on the development process, with a section in the about section about numbering and the release cycle? 21:43:59 <davidnind> loved the development process talk cait - was a great overview all in one place 21:44:17 <caroline> cait++ both presentations were great! 21:45:08 <caroline> The wiki is so big... trying to find the info in https://wiki.koha-community.org/wiki/Category:Development 21:46:05 <caroline> This ? https://wiki.koha-community.org/wiki/Release_maintenance 21:46:21 <cait> i think all technical 21:46:31 <cait> but the second shoudl be current at least 21:46:36 <caroline> Yes very. 21:47:37 <cait> we probably need something new 21:48:24 <caroline> Ok, so do we agree to write something very non-technical for end users to understand the development process/cycle? 21:48:38 <cait> +1 21:48:41 <davidnind> makes sense to me! 21:48:46 <caroline> #agreed write something very non-technical for end users to understand the development process/cycle 21:48:56 <caroline> appendix? faq? 21:49:15 <cait> faq still needs a major clean up 21:49:33 <cait> maybe a new section? 21:49:42 <caroline> or in the "about"? 21:49:44 <davidnind> I think as an appendix, but having a brief intro in about Koha section 21:50:06 <caroline> ok so appendix/new section 21:50:31 <caroline> #agreed the development process/cycle will be in an appendix 21:51:32 <caroline> #action caroline will add the development process section to taiga (just to remember to do it) 21:51:51 <caroline> #topic Set time of next meeting 21:52:32 <caroline> Do we want to change the time? 21:52:49 <davidnind> happy for it to be earlier if it suits you all better (https://www.timeanddate.com/worldclock/) 21:53:09 <caroline> earlier? I though it was like 7am in NZ 21:53:22 <cait> 11pm here os not against earlier 21:53:27 <davidnind> nearly 11am (daylight savings time) 21:53:53 <caroline> omg ok, so how about 8 for you? 21:53:56 <cait> we are moving in a few weeks... so might be even later then 21:54:16 <davidnind> what time is it for LeeJ 21:54:31 <caroline> Same as me I think. Right now it's almost 6 pm 21:55:12 <caroline> UTC 19? 21:55:21 <cait> what is now? 21:55:43 <davidnind> nearly UTC 22:00 21:55:58 <caroline> today's meeting was at UTC 21 21:56:15 <caroline> so it would be 2 hours earlier 21:57:09 <caroline> https://www.timeanddate.com/worldclock/meetingdetails.html?year=2018&month=10&day=2&hour=19&min=0&sec=0&p1=165&p2=22&p3=195 21:57:26 <cait> 19 sounds good 21:57:33 <caroline> Is Nov 6 ok? 21:57:46 <cait> yes 21:57:49 <davidnind> is fine with me 21:58:17 * caroline mutters don't mess it up... dont mess it up 21:58:34 <caroline> #info Next meeting: 6 November 2018, 19 UTC 21:58:45 <cait> heh 21:58:46 <caroline> #endmeeting