Archive for the ‘Fedora Documentation Project’ Category

Fedora Docs’ FAD 2014

2014-03-23 Leave a comment

It’s good to get a team together, face-to-face, that usually only meets virtually via IRC on occasion.  The Fedora Docs Project team recently had such an opportunity when they met in the Red Hat offices in Raleigh and Brno.  Linked by a video teleconference, the two groups converged to discuss new work-flows for Publican 4, hacking on some guides, discussing management issues, and working to get the new Docs website built and configured.  Here are some of the highlights of the event:

Work-flow update for Publican 4

The release of Fedora 20 also saw the release of Publican 4.  Publican 4 isn’t quite backwards compatible with the Publican 2 we were using so an update to our work-flow was necessary.  We’ve also made it to a point in our work where using the old web.git repo for publishing just isn’t working any longer.  The new way of publishing involves using Koji to build our documents in RPMs and place them safely into a repository where they can be grabbed by our backend server and be published to the world.  This change not only represents new commands but also a different mindset to publishing.  The new procedures were documented and tested so we’ll be able to start utilizing these as soon as our backend server gets fixed.

Guides hacked upon

You know those guides that seem to languish?  Yeah, I’ve got a few of those.  I did spend some time working on a few guides that will hopefully go live for Fedora 20 or 21.

Accessibility Guide

The Accessibility Guide has really taken a backseat in recent releases.  I’m not sure much has changed for many users but it’s good to keep the document current for any new users that may require a little assistance in making their computer work for them.  I was able to take a lot of stuff out of the guide, mostly GNOME packages that are no longer in Fedora and add a couple of packages I found for KDE.  I’m hoping I can do a better review of what’s available in Fedora before Fedora 21 comes around.

Amateur Radio Guide

I finally got around to adding CQRLOG to the guide.  I really love CQRLOG as a logging program so I’m happy to share some of that information with other amateur radio operators that come to Fedora looking for a FOSS solution for their radio activities.  John made a few additions as well so I suspect the next release will have some added goodness that people should find helpful.

Documentation Guide

This is where I spent most of my time working.  The style guide was moved from the wiki into the guide and other useful information was added as well.

Jargon Guide

This guide has never really seen the light of day.  This is due to the fact that translations of this guide would be nearly useless as they wouldn’t be in any particular order.  Publican 4 fixes this long-standing bug and so I, once again, have hope to publish this book.

Security Guide

Yeah, there’s always some hacking on the security guide when I’m around.  This time there was some testing of the new Yubikey Neo and getting them to do tricks inside Fedora.

New backend server

Jared worked very diligently to create a new backend server.  Unfortunately the documentation was lacking and so we weren’t able to complete the build.  Work continues on this effort.

Videos of the FAD

Because most of the event took place over our video chat you can watch the videos from the meeting: Friday, Saturday, and Sunday.


Announcing DocsGlue

2012-01-24 Leave a comment

mw-render replacement signMany Fedora Docs project contributors enjoy writing on the wiki using the WYSIWYG editor that is provided by MediaWiki.  This is great for contributors but not so much when we are trying to pull all this information into DocBook for formal release.  The solution was simple: Ian had to fix mw-render.

This all went down at FUDCon Blacksburg, just a couple weeks ago.  Ian and John got together to break, fix, or eliminate the tool we once used to do the conversion of MediaWiki text to DocBook.  Ian worked for several hours trying to piece code together to make mw-render work.  It did not, however, ever get off the ground despite his best efforts.  Several releases prior to the current version of mw-render the DocBook functionality was removed leaving it no longer useful for our needs.

Once it sunk in that mw-render was dead to us, we started looking for an existing solution.  We found many but none that would do exactly what we wanted.  Ian started drawing up plans for a replacement and we decided that if we were going to do the work to build a tool to do the conversions that we should really do it up right.

DocsGlue notesThis brings us to the project of DocsGlue.  The current vision of DocsGlue is a program that will take MediaWiki text, turn it into DocBook XML, then open a ticket in Red Hat’s Bugzilla instance for a certain guide and add the DocBook XML text as an attachment.  The guide owner can then easily use the attached file as source for a guide that can then be translated and published.

DocsGlue will be usable from both the command line and the GUI.  This will make it easy for anyone to use no matter how they like to operate.

This will hopefully reduce the amount of time spent on moving data from the wiki into our guides and also make this information a lot more useful for users looking for answers.

Currently the project is hosted on Fedora Hosted where all the source code will be available.

What to put into the Docs Project presentation at FUDCon Blacksburg?

2012-01-03 1 comment

Thanks to Robyn’s “Blacksburg FUDCon: Lets do this thing” blog post, I was reminded that not only am I presenting at FUDCon but that I also hadn’t even created the presentation!  Ack! I quickly downloaded the presentation template that she pointed out and started throwing information into it.  Of course this only led to more questions on my part; I can only imagine what other people would say.

So with that in mind I issue a challenge to the community: What do you want to know about the Fedora Docs Project?

This is especially an important question for those that are planning on attending the presentation at FUDCon in Blacksburg.  So if you have questions now is the time to ask!  I’ll not only help give this presentation but I’ll also provide the presentation and notes to all under the CC-BY-SA license.

So ask away!

Removing the Fedora Release Notes from the releases.

2011-09-11 Leave a comment

Twice a year the Fedora Docs team runs around with their hair on fire trying to get the Release Notes bits put together, translated, and packaged.  The packaging requirement puts a lot of strain on the process, though, as thousands of lines of code go into the documentation, they are all new every release, and most of the time are only available at the last minute based on changes to code in other programs.

To reduce the strain on the process I’d like to propose that the Release Notes not be packaged (in RPM) and included in the releases and only be made available on the Fedora Docs website.

This proposal will be sent to the Fedora Docs and I encourage anyone with an opinion on this to reply to that message.

Creative Commons License
Sparks’ Fedora Project Journal by Eric H Christensen is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

Help with FOP

2011-06-29 Leave a comment

Right around the time of the Fedora 15 release an upstream change to FOP caused problems with the Docs team.  What is FOP, you may be asking?  FOP is the software that Publican uses to create our PDFs.  Broken FOP means no PDFs for the end users to enjoy.

I think the latest patch has created a nice bandage on the problem but we are still looking for someone with Java experience to help engineer a better solution.  Take a look at the bug ticket and see if you can help.

Creative Commons License
Sparks’ Fedora Project Journal by Eric H Christensen is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

Fedora Docs QA Process

2011-06-11 Leave a comment
Notes from SELF 2011

At the SouthEast LinuxFest (SELF) a few Docs folks grabbed a room and started discussing some processes for QA with the Docs Project.

A few months ago the idea was had to have a QA team that would review the text and DocBook code to make sure what we are saying is correct and has consistent XML tags.  Several members stepped forward work this project but the process never really got off the ground and the organization never came together.

At the SELF FAD we tried to make the process easy and yet functional.  Basically we created two processes: new text and bug fixes.

The new text process involves creating the new guide/article, committing it to a repo, opening up a BZ ticket, having someone from Docs QA go through the guide making sure that the processes and procedures are correct and that the DocBook XML tags are correct and consistent, then branching the repo and publishing.  Similarly, bug fixes have their patches reviewed prior to be committed to the branch for publishing.

Not only does this give us the opportunity to “clean up” our documents before they hit the streets, this will also give us an opportunity to engage our new contributors that may not be experienced with writing in DocBook XML.

This is by no means the new “policy” but rather a proposal.  Discussion will be over on the Docs List.  I’m hoping this proposal is a win-win situation for Docs!

Categories: FAD, Fedora Docs QA

Stepping down as Documentation Project Leader

2011-01-26 Leave a comment

Some of you might have noticed, between sips of highly caffeinated beverages and furiously typing out all the great documentation that this group provides, that I haven’t been around that much lately. Unfortunately just before Christmas I was given a new boss and new responsibilities that changed my daily schedule. This, on top of other changes to my daily schedule, has severely limited my ability to provide a near-constant presence in the Fedora community. As much as I hate to do this I feel that I must step down as the Documentation Project Leader to allow someone with more cycles in their day to continue the work.

This isn’t a bad thing by any stretch of the imagination. It was probably time for someone with new and different ideas to step up and keep the project interesting. There have been a lot of changes under my watch and I can hardly wait to see the changes that occur under the next watch.

Back in November when we were entertaining the thought of holding elections for my position, Zach Oglesby came to me and said that if I needed to bail out of the position that he might be willing to take on the responsibilities. Since then I’ve been talking with Zach and today he agreed to take on the position. I’m very excited about him accepting the position as he has been involved in every aspect of the project for a while and I know he has some exciting ideas about moving the project to the next level.

Thanks to everyone who helped me through the years (two?) that I’ve held this position. Every contributor to this project has made it successful and for that I am grateful to you all.