14:02:00 <randomuser> #startmeeting Docs Project Meeting - Agenda: https://fedoraproject.org/wiki/Docs_Project_meetings
14:02:00 <zodbot> Meeting started Mon Jun  8 14:02:00 2015 UTC.  The chair is randomuser. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:02:00 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:02:02 <randomuser> #meetingname Fedora Docs
14:02:02 <zodbot> The meeting name has been set to 'fedora_docs'
14:02:04 <randomuser> #topic Roll Call
14:02:25 * zoglesby is here
14:02:28 * jjmcd 
14:02:34 <wdashley> wdashley is here
14:02:53 * smccann is here
14:03:02 <zoglesby> randomuser: no more pingdocs?
14:03:16 <randomuser> more of a scheduling problem :P
14:03:32 <bexelbie> .hello bex
14:03:35 <zodbot> bexelbie: bex 'Brian (bex) Exelbierd' <bex@pobox.com>
14:04:28 * Capesteve waves
14:05:46 <grundblom> Hello everyone!
14:06:30 <randomuser> good turnout today, nice
14:07:18 * pbokoc 
14:07:20 <randomuser> we'll skip action items, none from the last meeting
14:07:28 <pkovar> /me is here
14:07:31 <randomuser> #topic New Writer Check-In
14:07:44 <randomuser> wdashley, that's you! how are you settling in?
14:07:54 <wdashley> getting there
14:08:15 <wdashley> still have a lot of git to learn mostly
14:08:51 * randomuser nods
14:09:11 <randomuser> just needs practice, like anything else :)
14:09:20 <randomuser> any questions while we're all here?
14:10:57 <wdashley> BTW, lnovich and I are in contact with each other.
14:11:24 <randomuser> great!  You know where to find anyone if questions arise, I won't put you on the spot for too long :)
14:12:00 <randomuser> #topic Release Notes
14:12:13 <randomuser> #action randomuser to award beat writing badges
14:12:43 <randomuser> not a lot more to say here, other than to thank everyone for making it a great release
14:12:51 <randomuser> #topic Publishing
14:13:18 <randomuser> I don't have any progress to report on this since the last meeting, unfortunately
14:14:00 <randomuser> jjmcd, I have a VM set up for publishing, when the amateur radio guide needs publishing, let me know
14:14:12 <randomuser> #info randomuser is offering publishing services for the time being
14:14:13 <bexelbie> randomuser, we should work on this together .. it will help our preso
14:14:20 <jjmcd> Roger hope to get the DNF chapter done soon
14:14:27 <jjmcd> at that point it should be ready
14:15:14 <randomuser> bexelbie, yeah.  I need to get something out to you, today.  I'm suffering from "must be *this* complete to share" syndrome, and will get over it
14:15:38 <randomuser> #info bexelbie and randomuser to deliver docs talk at Flock
14:15:42 <bexelbie> randomuser, if it would help, I can show you some of my horrifying unfinished ideas
14:15:59 <randomuser> bexelbie, it'd be a confidence booster, at least :)
14:16:17 <bexelbie> :D
14:17:09 <randomuser> are there any questions about current or prospective publishing stuff?
14:17:26 <randomuser> also, ACK jjmcd
14:17:48 <zoglesby> randomuser: I have lots
14:17:52 <zoglesby> but not for the meeting
14:18:06 <zoglesby> I just don't know what is going on now as I have been away for a while
14:18:26 <randomuser> zoglesby, let's get together and talk about it soon, then.
14:18:31 <zoglesby> indeed
14:20:05 <randomuser> #topic Guide Status
14:20:34 <randomuser> we have a *lot* of guides published for F22.  More than most/all recent releases.
14:20:40 <randomuser> Kudos to all the guide writers!
14:21:52 <randomuser> I published the multiboot guide, and asked for feedback on users@
14:22:19 <randomuser> one person asked for something on dual booting with el6/grub legacy; the rest of the feedback was positive
14:22:38 * lnovich is here
14:22:53 <randomuser> a simple book, but my first one to write from scratch, yay!
14:23:15 <Capesteve> congrats randomuser
14:23:24 <Capesteve> randomuser: ++
14:23:33 <lnovich> sounds great!
14:24:00 <Capesteve> We once spoke about have a "short cut link" for the System Admin Guide. I would like to add live links to the Sys Admin Guide in the Networking Guide. Shall I wait for this magic versionless links or just go ahead with full links to Fed22 version?
14:24:53 <randomuser> erm... hang on, capesteve, I'll find notes.  I did add a bunch recently
14:25:42 <randomuser> in the meantime, there are a couple guides outstanding we should throw some time at
14:26:11 <randomuser> the accessibility guide was updated by kendall clark and bcotton
14:26:39 <randomuser> sclark has been working on a firewall guide, I bet that could be caught up and published
14:26:55 <randomuser> jjmcd's amateur radio guide, which we already touched on
14:27:17 <randomuser> maybe more?
14:27:31 <randomuser> anyone want to take action items from that list?
14:27:58 <smccann> what are you asking for? someone who can publish them? someone who can edit the existing content?
14:28:05 <Capesteve> Do you want me to proof read firewall Guide?
14:28:19 <randomuser> Capesteve, yes, that would be great
14:28:28 <Capesteve> roger that
14:29:30 <randomuser> Capesteve, if you find it lacking, maybe make bugs and we can all pitch in?
14:29:53 <Capesteve> ok
14:30:07 <randomuser> smccann, someone to say whether or not they're ready to publish, and share what needs to be done if not
14:30:24 <randomuser> #action Capesteve to review networking guide
14:30:40 <randomuser> #action randomuser to prod bcotton about accessibility guide status
14:30:54 <smccann> I can proof-read accessibility but not sure I could tell if something was wrong or missing
14:31:03 <randomuser> Capesteve, https://infrastructure.fedoraproject.org/cgit/ansible.git/commit/?id=dd440f21d1fdd568eb43c7575dafbef6947d2c93
14:31:14 <Capesteve> randomuser: you made a mistook, firewall not networking
14:31:20 <randomuser> bah
14:31:22 <randomuser> #undo
14:31:22 <zodbot> Removing item from minutes: ACTION by randomuser at 14:30:40 : randomuser to prod bcotton about accessibility guide status
14:31:25 <randomuser> #undo
14:31:25 <zodbot> Removing item from minutes: ACTION by randomuser at 14:30:24 : Capesteve to review networking guide
14:31:34 <randomuser> #action Capesteve to review firewall guide
14:31:40 <randomuser> #action randomuser to prod bcotton about accessibility guide status
14:33:29 <randomuser> I'm going to throw a semi-related, unscheduled topic in now, hang on
14:33:38 <randomuser> #topic API documentation
14:33:53 <zoglesby> randomuser is breaking the rules!
14:33:56 * lnovich runs in the opposite direction!
14:34:19 <randomuser> #info Fedora developers are starting to focus on API stability to enable developers of both internal and third party code
14:34:43 <randomuser> #info documented APIs are more usable than undocumented APIs
14:34:58 <lnovich> some are already documented
14:35:04 <randomuser> this is something that I think sgallagh was going to bring up to us
14:35:16 <jjmcd> Heck, reverse engineering the API is part of the fun of grokking code
14:35:29 <randomuser> lnovich, not documented as "things Fedora offers developers" in any official docs
14:35:48 <sgallagh> randomuser: Right, so the Fedora Server group has started this exploration
14:35:53 <lnovich> the question is do we maintain documentation on an API that is already documented elsewhere - in another project
14:36:05 <sgallagh> We're going to look into a set of APIs that we know to be stable and try to gather them in a single Fedora-maintained location
14:36:07 <randomuser> sgallagh, good, you're here :) your stage
14:36:44 <zoglesby> randomuser: is d.fp.o the best location for that? Is docbook/publican the best solution for it?
14:37:06 <jjmcd> A consistent style for the common APIs would be a huge win
14:37:17 <randomuser> I would argue that docbook/publican is *not* the best solution, and here's why:
14:37:27 <lnovich> especially if engineers can contribute content
14:37:47 <sgallagh> lnovich: So, that's a really good question. I'd argue that at *minimum* we should aim to provide a consistent browser and search function, even if we end up linking to external documentation
14:37:49 <zoglesby> randomuser: I agree, and need to reason!
14:38:21 <randomuser> I think this is a great idea, but I'm not sure we have the manpower to manually compile and keep up to date.  So, programatically generated documentation, or at least a programatically generated skeleton, would be more sustainable
14:38:40 <bexelbie> +1
14:38:40 <randomuser> and I think that would be easier to do if outputting not-xml
14:39:21 <randomuser> and we will need a fair amount of engineering direction, sgallagh - is the server WG prepared to provide specifications and SMEs?
14:39:25 <bexelbie> sgallagh, are you envisioning a collection fo API docs for all of the packages in a given Fedora release? essentially frozen snapshots of hte upstream project in a more cohesive format?
14:39:28 <lnovich> something like ReST or markdown would be something that may be better?
14:40:09 <sgallagh> randomuser: Server WG is planning to start this, though I've had rumblings from the Base WG to take it over as well
14:40:16 <sgallagh> So you should have the engineering assistance you need
14:40:21 <randomuser> excellent
14:40:44 <sgallagh> bexelbie: Absolutely not. We're looking for a limited set of curated APIs that we are claiming compatibility for beyond just the current release.
14:41:06 <lnovich> how far away are we from a new toolchain / publishing system randomuser?
14:41:11 <sgallagh> bexelbie: Basically, we want to address the "upgrade nervousness" by advising people on which things we guarantee won't change.
14:41:12 <randomuser> so, glibc, python, maybe?
14:41:17 <sgallagh> (or change incompatibly, anyway)
14:41:32 <sgallagh> randomuser: Those are definitely the first ones to point at.
14:41:43 <bexelbie> sgallagh, ok, cool
14:41:46 <sgallagh> Probably some of the D-BUS APIs that are stable as well, like Network Manager
14:41:48 * bexelbie is much happier to hear that
14:42:19 <randomuser> lnovich, not far.  I haven't gotten a lot of feedback on implementation questions, or had much time to work on it.  I'll take questions out of band, though :)
14:42:54 <lnovich> ok
14:43:02 <jjmcd> An issue I see it that engineer-produced dox are traditionally crap, and I wonder whether we want to put our brand on that.  Perhaps docs-curated, but even just glibc that is a pile of work
14:43:09 <randomuser> sgallagh, on an unrelated note, a short "how to write a role" thing might be nice too.  I'd work with you on that if you're interested.
14:43:51 <sgallagh> randomuser: I'm planning on working on that within the next month (in preparation for my "Write your first server role" workshop at Flock)
14:43:58 <sgallagh> So I'd appreciate your assistance, sure :)
14:43:59 <randomuser> nice
14:44:40 <randomuser> sgallagh, well, let's talk about it.  I can take notes at the workshop, or we can plan ahead and have a reference published to coincide with it.
14:45:18 <sgallagh> randomuser: Having a reference published ahead of time would be best. It'll help me design the workshop and provide me with reference materials for those attending as well
14:45:47 <lnovich> is there a specific API you want to start with sgallagh?
14:45:47 <randomuser> great, let's do it
14:46:25 <randomuser> Back to this API reference, I'm hoping some of the more professional writers here will be able to put together an action plan
14:46:44 <sgallagh> lnovich: I've been talking about glibc mostly (but that's going to be a big one). But maybe starting with the systemd D-BUS API would be a good place. (It's declared stable upstream)
14:46:57 <sgallagh> And it's considerably smaller
14:47:10 <randomuser> as long as we're not doing it for gnome extensions :P
14:47:12 <lnovich> smaller is better for a pilot
14:47:19 <sgallagh> lnovich: My thoughts exactly
14:47:33 <lnovich> the libvirt API is documented for the most part
14:48:18 <randomuser> so what's actionable here?
14:48:36 <lnovich> 1. pick an API as a starter
14:49:03 <lnovich> 2. design a template / framework for documenting it
14:49:24 <lnovich> 3. Make a How to document APIs guidebook
14:49:32 <jjmcd> lnovich, I think you need a toolchain before 2.
14:49:36 <lnovich> 4. Documnent the API
14:49:53 <jjmcd> (assuming we're not using docbook)
14:50:09 * randomuser nods
14:50:18 <randomuser> writing the toolchain will be the fun part
14:50:19 <lnovich> ok so we need to agree on a tool
14:50:40 <jjmcd> I wonder whether some sort of a style guide for doxygen might work
14:50:47 <lnovich> is there a "shortlist" we can put out for a vote?
14:50:49 <randomuser> sgallagh, is it too early to pick one API or another?
14:51:04 <sgallagh> randomuser: Not at all
14:51:04 <jjmcd> I kind of like the markdown idea excect that no two implementations seem similar
14:51:21 <randomuser> I would lean towards ReST, as I've been working with it lately
14:51:29 <lnovich> this is why we need a template - for whatever tool we pick
14:51:40 <lnovich> I made an online help system in ReST
14:51:44 <lnovich> it can be done
14:52:02 <randomuser> lnovich, where's the code?  I could use a reference :)
14:52:30 <randomuser> #action randomuser to continue API discussion on list
14:52:42 <randomuser> ... it looks like this could carry on for a while
14:52:44 <lnovich> unfortunately it was for a company I worked for before Red Hat, and that company went belly up and all the IP was sold
14:54:08 <randomuser> bexelbie, we still have personas (and related topics) on the agenda, want a few minutes on that?
14:54:16 <Capesteve> jjmcd: I agree markdown is too inconsistent to use for any doc you intemd to maintain over time
14:54:31 <bexelbie> randomuser, there have been no new responses - the only thing imho is folks - answer your email :)
14:54:52 <randomuser> #action everyone to use better filters for their docs list mails
14:55:27 <randomuser> #topic Outstanding BZ Tickets
14:55:37 <randomuser> #link http://tinyurl.com/lbrq84
14:55:42 <randomuser> EOF
14:55:48 <randomuser> #topic Open floor discussion
14:55:55 <randomuser> what'd we miss?
14:55:59 <lnovich> FLOCK - who's going
14:56:25 <lnovich> Open Help Conf? Texas Linux Conf? anyone ? Bueller?
14:56:33 * bexelbie is going to flock
14:56:49 <lnovich> has the CFP deadline closed already?
14:56:51 <randomuser> I was considering the open help conference, but nobody replied on the list to say they were considering too
14:57:02 <randomuser> lnovich, yes, for several weeks now
14:57:07 <randomuser> bexelbie and I are doing a talk
14:57:13 <lnovich> what about?
14:57:24 <randomuser> about Fedora Docs workflow and tooling changes
14:57:36 <randomuser> ... at least, that's my idea of it :)
14:57:41 <bexelbie> +1 :D
14:57:49 <lnovich> Love to see it
14:58:00 <randomuser> pbokoc should go, I'd bring interesting beer for sampling
14:58:38 <pbokoc> randomuser, what, flock?
14:58:44 <randomuser> yes, flock
14:58:49 <pbokoc> too far
14:58:54 <randomuser> swim!
14:59:13 <randomuser> lnovich, are you attending?
14:59:47 <lnovich> I will be in the US for the summer
15:00:13 <lnovich> I will be in Florida, so if I go it is at my own expense
15:00:18 <randomuser> nice
15:00:37 <lnovich> I will be working from there - taking the kids to see grandma/grandpa
15:00:38 <jjmcd> Florida in August, maybe not so nice
15:00:42 <randomuser> FL to NY is cheaper than flying from home, I'm sure :)
15:00:47 <lnovich> much
15:00:58 <Kellin> FL is beautiful in August - what part?
15:01:02 <randomuser> Okay, our time is up, thanks for coming everyone
15:01:06 <lnovich> Lake Worth
15:01:18 <randomuser> after party in #fedora-docs
15:01:26 <randomuser> #endmeeting