14:02:39 <bexelbie> #startmeeting Fedora Docs
14:02:39 <zodbot> Meeting started Mon May 22 14:02:39 2017 UTC.  The chair is bexelbie. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:02:39 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:02:39 <zodbot> The meeting name has been set to 'fedora_docs'
14:02:52 <bexelbie> #topic A little bit of AsciiDoc Conversion
14:02:55 <bexelbie> .fas bex
14:02:56 <zodbot> bexelbie: tqtwr 'gsafd' <mesabexudi@top1mail.ru> - ybexwqmxnx 'ybexwqmxnx yhdgb' <ybexwqmxnx@nowmymail.com> - bexhet '' <bexhet@hotmail.it> - lonelyibex 'fungo' <lonelyibex@gmail.com> - moko 'moko lee' <ibex@msn.cn> - sfarr01 'Steven Farr' <sfarr@bex.net> - mcreps 'Merl Creps Jr' <merljr@bex.net> - tbex 'Tony Beckham' <t2yb5m@gmail.com> - efjiwmos 'takagiatuko' <bexroll@gmail.com> - makubex 'Bruno Lopes de Mello' (2 more messages)
14:03:00 <mayorga> .hello mayorga
14:03:01 <bexelbie> .hello bex
14:03:01 <zodbot> mayorga: mayorga 'Eduardo Augusto Mayorga' <e@mayorgalinux.com>
14:03:03 <zodbot> bexelbie: bex 'Brian (bex) Exelbierd' <bex@pobox.com>
14:03:11 <bexelbie> o/ mayorga
14:03:16 <mayorga> bexelbie: o/
14:03:32 <bexelbie> terminal__, mayorga barring objections I am not going to go through the entire agenda as I think we are all being motiviated by terminal__ :)
14:03:42 <terminal__> haha
14:03:49 <bexelbie> However, any lurkers are free to speak up and we can "Agile Coffee" an agenda up for ya
14:04:02 <terminal__> I'm just motivated to get this conversion moving
14:04:19 <bexelbie> To set some context, terminal__ please correct me if I get the details wrong, ...
14:04:28 <terminal__> I learned asciidocs and it's a lot easier than using publican
14:04:33 <bexelbie> terminal__, wrote to the mailing list about converting the Sys Admin guide from DocBook to AsciiDoc
14:04:47 <bexelbie> terminal__, also noted taht we haven't been meeting and wanted to know what hte next steps were
14:04:57 <bexelbie> I suggested he look at docsii and we are now at this point in time
14:05:08 <terminal__> yes
14:05:19 <terminal__> my repo is: https://pagure.io/fedora-docs/asciidocs-sysadmin
14:05:25 <bexelbie> As a markup, AsciiDoc is easier to hand create than DocBook, I agree - DocBook can be very expressive though
14:05:29 <mayorga> Bookmarked.
14:05:46 <terminal__> I've converted the sysadmin guide using docscii already
14:06:05 <terminal__> there's some links and such that need cleaning up, and probably some formatting, but it did a good job
14:06:37 <terminal__> it already had an option in docscii to use the publican.cfg file to prepare the document
14:06:43 <bexelbie> Cool - I know the author of hte tool would love an issue or PR to help clean up any errors it is making
14:07:20 <terminal__> One of the links it converted, it didn't properly convert, I think because of a space in the URL
14:07:41 <bexelbie> #link DocsII https://github.com/clayts/docscii
14:07:48 <bexelbie> #info DocsII https://github.com/clayts/docscii
14:07:58 <bexelbie> #info terminal__'s repo https://pagure.io/fedora-docs/asciidocs-sysadmin
14:08:07 <terminal__> I had the same problem initially trying to work out how to convert it to a URL, I ended up using the %20 symbol
14:08:11 <bexelbie> terminal__, that would be good feedback for the author
14:08:30 <bexelbie> sounds like that should at least be warned on - as technically you should need a %20 aiui
14:08:49 <terminal__> I'll put the feedback up on github
14:09:21 <terminal__> things I've noted in conversion
14:09:47 <terminal__> some of the formatting we've used in publican doesn't quite convert the same directly to asciidocs
14:10:02 <terminal__> probably have to use markup or something to get that
14:10:30 <bexelbie> terminal__, can you start a list of the types of cleanup you're doing and can you flag that markup failure for conversation so we can make some decisions as a group?
14:10:40 <bexelbie> I suspect we can find a way to do this without having to mix markups
14:10:51 <bexelbie> also, we may decide that some formatting just isn't needed
14:10:53 <terminal__> in the docbook version of the guide, the chapter synopsis was rendered as a labelled list in the pdf
14:11:09 <terminal__> which obviously when we convert to topics isn't going to be such an issue anyway
14:11:19 <bexelbie> yep
14:11:24 <terminal__> yeah no worries, I'm recording issues as I go
14:11:50 <bexelbie> cool!
14:12:17 <terminal__> I've kinda been just doing general issues, not related to the document changes I'd been making but that was all from when i started from scratch
14:12:48 <terminal__> so it was more related to issues I was finding trying to write the document from scratch
14:13:16 <terminal__> one other issue i've come across so far, is the 'figures' aren't numbered after the chapter numbers
14:13:26 <terminal__> I can't work out how to do that at this time
14:13:39 <terminal__> maybe manually?
14:13:46 <terminal__> probably via attributes or something
14:13:53 <bexelbie> terminal__, I suspect so
14:13:57 <terminal__> turn off sector numbering for that particular part of the document
14:13:59 <bexelbie> Can I offer some research suggestions?
14:14:02 <terminal__> sure
14:14:27 <bexelbie> 1. Really look through and make sure this is a problem we should solve first, if at all ... punting on this with a known issue may not be bad
14:14:33 <bexelbie> 2. Checkout how OpenShift does it
14:14:43 <bexelbie> They have been doing AsciiDoc for a while and have some solutions that are really good
14:14:51 <terminal__> ah ok
14:14:57 <bexelbie> https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc
14:15:04 <bexelbie> that is a link to the right repo and a starting point
14:15:25 <terminal__> cool
14:16:13 <bexelbie> The other thing, If you don't mind doing it
14:16:25 <bexelbie> is could you look at AsciiBinder (http://www.asciibinder.org/) ?
14:16:27 <bexelbie> specifically
14:16:35 <bexelbie> please look at the _topic_map.yml file they use
14:16:39 <bexelbie> we are probably going to use this for publishing
14:16:43 <bexelbie> and it replaces your master.adoc
14:17:05 <bexelbie> here is a link to the one used by openshift
14:17:05 <bexelbie> https://github.com/openshift/openshift-docs/blob/master/_topic_map.yml
14:17:05 <terminal__> ah ok
14:17:25 <bexelbie> here is one used in the budget website
14:17:26 <bexelbie> https://pagure.io/fedora-budget/blob/master/f/_topic_map.yml
14:17:36 <bexelbie> The budget website is my PoC on publishing in Fedora with AsciiBinder
14:17:44 <bexelbie> I am trying to work on the rest of the tooling
14:17:59 <bexelbie> Making your repository a valid asciibinder repository would be awesome
14:18:03 <terminal__> no worries
14:18:12 <terminal__> I'll see what I can do.
14:18:13 <bexelbie> we can work on styling once you have something that builds
14:18:29 <bexelbie> ryanlerch, has already done some work on the styling
14:18:32 <bexelbie> we just have more to do
14:18:39 <bexelbie> (and now two Ryans to help with it)
14:18:46 <terminal__> heh
14:19:20 <terminal__> btw, I'm in Australia, so that's probably why no one's on when I get into IRC, although it seems to be that everyone lurks anyway
14:19:36 <bexelbie> There is far more lurking than we'd like ... but yes, that is why
14:19:48 <bexelbie> by coincidence, I'll be near your timezone for the next two weeks in Japan
14:19:56 <terminal__> sweet
14:19:58 <bexelbie> however, I will be missing the meetings on Mondays
14:20:09 <bexelbie> but if you want you can email me or ping me on Telegram (@bexelbie)
14:20:13 <bexelbie> I may not have good IRC access
14:20:19 * bexelbie will try to set up Riot
14:20:19 <terminal__> ok
14:20:33 <bexelbie> The other Ryan is also in Australia
14:20:45 <bexelbie> or at least a timzeone near that
14:20:47 <terminal__> haha how coincidental
14:21:01 <bexelbie> Howwever he focuses more on the design - but he is also great with docs themselves
14:21:08 <bexelbie> he is a big Magazine contributor
14:21:22 <terminal__> ah yeah, I read the magazine pretty regularly
14:21:52 <bexelbie> cool
14:22:07 <bexelbie> oh, you had asked me about "content challenges" - tell me if I am changing the subject too soon
14:22:28 <terminal__> no that's fine, I was just summing up what we've covered so far, in my head
14:22:38 <terminal__> :D
14:23:06 <terminal__> what did you mean by 'content challenges'
14:23:46 <bexelbie> Basically, if you find things that are missing, bad or needing of help, make a list of them.  Do not feel you have to fix it all
14:23:53 <bexelbie> we can start an easy fix and please fix set of lists/tickets
14:24:12 <bexelbie> This is a lot you've had tossed at you - so dno't think you are under pressure to do it all, do it all right now, or do it perfectly
14:25:00 <terminal__> yeah I'd already come across some wordings that I felt could be improved a little in the first few challenges
14:25:20 <terminal__> I was also looking at X11 refs and wondering if they even applied considering we're mostly using wayland now
14:25:41 <terminal__> need to spin up a test box and try things out
14:26:12 <terminal__> see if there's a better way
14:26:14 <bexelbie> terminal__, that may be a good candidate to move to an Appendix (module) for retaining until X11 is out
14:26:25 <terminal__> sure
14:27:28 <terminal__> regarding the 'next lot of meetings'
14:27:53 <terminal__> obv it's been pretty quiet around here for months until i 'stirred the pot' so to speak
14:27:54 <bexelbie> ?
14:28:15 <bexelbie> so a lot of people got pulled into side projects, $dayjob and $life over the last few months
14:28:28 <terminal__> yeah
14:28:34 <bexelbie> I have been working on a new tooling PoC which is viewed as a blocker by many and I haven't gotten my blog about it out
14:28:44 <bexelbie> there was a second tooling proposal and I don't think they are still active
14:28:51 <bexelbie> so barring objections, my PoC will be it
14:29:12 <bexelbie> The PoC is blocked by an infra need from loopabull, which is coming soon
14:29:22 <bexelbie> If I can find the time, I will write it up with the holes so it can be poked at
14:29:25 <terminal__> I have no objections, I just want to be able to pass ideas by people and discuss what's being worked on
14:29:36 <bexelbie> honestly, your work on this guide will be helpful because I can just show real content then :)
14:29:38 <terminal__> which seems to be just what i'm doing :P
14:29:45 <bexelbie> it is what you're doing
14:29:48 <terminal__> haha
14:29:50 <bexelbie> the ML is also good for that
14:29:57 <bexelbie> as meetings are hard to get going these days
14:30:00 <bexelbie> but they ahve a real value
14:30:04 <terminal__> yeah
14:30:37 <terminal__> even the docs room is usually dead, so although I have to stay up late to get to these meetings, at least there's people in here when they happen
14:31:05 <bexelbie> we can also work to have conversations at times more convenient for you ... I am usually in Europe
14:31:10 <bexelbie> mayorga, is in LATAM though :)
14:31:21 <bexelbie> Pete, the docs lead, is in US Central - so ML may be best
14:31:30 <terminal__> what is ML?
14:31:37 * mayorga is on UTC-6.
14:31:59 <terminal__> UTC+8 here
14:32:12 <terminal__> 10:32 pm
14:32:34 <bexelbie> ML == mailing list
14:32:39 <terminal__> ahh yeah
14:32:44 <terminal__> makes sense :D
14:32:44 <bexelbie> UTC +2  :)
14:32:54 <bexelbie> almost literally splitting the difference
14:33:08 <terminal__> pretty much, but closer to my tz
14:33:27 <terminal__> 6 hrs
14:34:52 <terminal__> I'll run up a telegram also maybe, ping on that if needed while you're in japan, you'll be a lot closer (if not in) my tz when you get there
14:35:55 <terminal__> so yeah that's probably about all I had, just wanted to cover the things I've been doing with asciidocs, and just make sure I wasn't going to break everything ;)
14:36:17 <bexelbie> sounds good!
14:36:41 <terminal__> make sure no one else was working on what I was working on, prevent duplication of effort, get the right tools for the job etc
14:37:14 <bexelbie> You're doing the right thing and stirring a pot that needed stirring :)
14:37:28 <terminal__> I could pretty much run up an asciidocs repo for each guide if you wanted it, push everything through Docsii
14:37:39 <terminal__> upload, then we can work on it as time allows
14:38:13 <bexelbie> terminal__, I think there could be some value in that however, I wonder if it wouldn't be better to focus on one document first to learn the process
14:38:20 <bexelbie> then apply that to the next one so we have consistency
14:38:25 <terminal__> yeah I was considering that too
14:38:35 <bexelbie> the other is that not every document is going to be worthy of publishing forward
14:38:38 <bexelbie> some are terribly outdated
14:38:50 <terminal__> of course
14:38:53 <bexelbie> we can at a minimum in this round cut the chaff
14:39:01 <bexelbie> even if we don't go full modular
14:39:56 <terminal__> Yeah I'll get this one moving, when I have time of course, I can't devote every day to it, but I have some free time in the evenings
14:40:06 <bexelbie> terminal__, you're not alone in being pressed for time
14:40:35 <terminal__> when I'm not busy with work stuff, and im supposed to be studying certs (IT guy) and I've got the odd social thing in between
14:40:57 <terminal__> but I don't like seeing things stagnate
14:41:03 <bexelbie> I hope you also get some even social
14:41:17 * bexelbie has to work on renewing his RHCE ... another thing for the list
14:41:33 <terminal__> I wanted to do my RHCSA this year, but its not going to happen
14:41:43 <terminal__> boss said I had to focus on puppet certs
14:42:18 <bexelbie> I've only done a little config management using Ansible
14:42:22 <bexelbie> I've heard good things about puppet
14:42:49 <terminal__> puppet is cool, but our main guy is between two projects so he's kinda not able to get the ball rolling properly
14:43:31 <terminal__> he's only in the office a few days a week, so that's why puppet certification is high on the priority list
14:44:03 <bexelbie> it's good stuff
14:44:16 <bexelbie> I had the privlege of getting confused at Config Management Camp one year
14:44:36 <terminal__> :P sounds interesting
14:44:58 <bexelbie> I have a meeting in 15 min - so I am going to prep for that in a few
14:45:01 <bexelbie> any other docs issues?
14:45:05 <bexelbie> not that the conversation isn't good
14:45:23 <bexelbie> terminal__, it is a bit of a hike for you http://cfgmgmtcamp.eu/
14:45:32 <bexelbie> but if you ever come to FOSDEM it is usually the 2 following days
14:46:11 <terminal__> I think that's it, I'll focus on going through the sysadmin guide, look at asciibinder, read up the openshift way, and yeah
14:46:27 <bexelbie> cool
14:46:29 <bexelbie> oh -
14:46:35 <bexelbie> Openshift has a weird way of doing links
14:46:40 <bexelbie> I haven't fully read it yet
14:46:47 <bexelbie> but it is apparently good and powerful
14:46:54 <terminal__> I've been reading the asciidocs usermanual
14:46:59 <bexelbie> what isn't clear from their guide is that there is a preprocessor for it that runs before asciibinder
14:47:10 <bexelbie> if you think it has power I'll find the script that is the preprocessor
14:47:14 <bexelbie> I have a link to it somewhere
14:47:23 <terminal__> sure
14:47:29 <bexelbie> either way, it'd be great to hear your assesement
14:47:44 <terminal__> I'll keep you updated as I go
14:47:53 <terminal__> ML or telegram, whatevs
14:48:23 <bexelbie> perfect!
14:48:28 <bexelbie> I am going to end the meeting ok?
14:48:38 <terminal__> yep I'm good with that
14:48:56 <terminal__> thanks for chatting
14:49:02 <bexelbie> #endmeeting