Ohio Linux Fest 2011, days 0 and 1

Yesterday I had the privilege of catching a ride with a couple of the Fedora Docs rockstars (Eric Christensen and Zach Oglesby) to Ohio Linux Fest.  Zach took the train down from Baltimore, and Eric drove up from Newport News to pick Eric and I up.  We then wound our way through Virginia, West Virginia, Maryland, Pennsylvania, West Virginia (again), and Ohio.  Eric was following directions from Google Maps, and while I had no complaints about the scenic views, there were a few times we all wondered if we were really going to end up in Ohio.  (At one point when we came to a narrow one-lane bridge across a swollen river, we even hopped out of the car and took pictures.  Unfortunately, my SD card stopped working so I didn’t get a good picture.)

Last night we hacked on some of the Fedora documentation until around 1:00am. I fixed up some bad formatting in the User Guide so that it would build again, and fixed a few other minor issues.

This morning, I got up early to help some Fedora contributors with their travel arrangements for FUDCon Milan, and ran the FUDCon planning meetings for FUDCon Milan and FUDCon India.  After a quick lunch (thanks to my friends at cloud.com), I headed back upstairs to the docs hackfest room and dove back into fixing up some more docs.  This afternoon, I worked on the Cloud Guide, a bit on the Security Guide, and showed some of the other guys some tricks I use for finding invalid DocBook tagging and fixing it.  I also helped Clint Savage with a couple of minor RPM packaging problems.  Now I’m helping John McDonough proofread a draft version of the Release Notes for Fedora 16.

I’m very much looking forward to the conference tomorrow and the Docs FAD on Sunday.

Documentation (or the lack thereof)

Check out the yellow labels -- what do the rest of the buttons do?I’m in Seoul, Korea this week teaching one of the ever-popular Asterisk Bootcamp classes.  As luck would have it, my hotel room has the most amazing remote control in the world!  Not only does it control the big ol’ LCD TV and the DVD player, but it also controls the air conditioner and all the lights in the room (including both lights in the bathroom!)

In trying to actually use the remote control, however, I was given a stark reminder of how important documentation can be.  As you probably already know, I try to take an active role in the documentation teams for both Asterisk and the Fedora Project, but never seem to make the time to write as much as I’d like.  As such, I can only hope our documentation efforts are more effective than the yellow labels on my remote control — just documenting the bare minimum and forcing the user to experiment to do anything useful (and very likely getting lost in the process).

(It’s my own personal opinion that this is one of the ways that free/open source software often fails to keep up with it’s commercial rivals; Many open source projects can’t afford to hire technical writers, and if they’re lucky enough to have volunteers do the work, there often isn’t much praise for the hard work and effort that goes into it.)

If this reminder has you feeling the same way I am, why not step up to the plate and help out on the documentation front?  After all, the fearless leader and the rest of the docs crew needs your help!  As the old adage goes… many hands makes light work!  We’d be glad to have you join our ranks.

My first thoughts on Publican

So as part of my work with the Fedora Documentation team, I’ve started playing around with Publican. For those of you who aren’t aware, Publican is a documentation tool chain that started out being used internally at Red Hat (where it was called documentation-devel), and is now being opened up and hosted by Fedora. I won’t bore you with all the details yet, but needless to say it makes it easy to get started with writing documentation in DocBook format and getting that documentation packaged up correctly. Continue reading below if you’d like to know more. (If you could care less about documentation, just be on your toes — the docs team is gonna be a lot more efficient in the near future!)

Continue reading My first thoughts on Publican