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