Announcing DocsGlue

Many 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.

This 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?

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.

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.

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

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.

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

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!

Stepping down as Documentation Project Leader

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.

Security Guide for Fedora 14 available

I’m late…  I’m quite late.  This should have been done a few weeks ago but it wasn’t but now I’m working on it.

The Fedora 14 version of the Security Guide is now available on the Fedora Documentation website.  Take a look at it and let me know of any changes/bugs.

Translation PO files will be made available shortly and as soon as translations are complete they will be published as well.

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

Packaging "links to Fedora Documentation"

I’m trying to figure out a way to provide links to the Fedora Documentation on the desktop.  GNOME currently has a spot to put documentation (it shows up under the System tab) and I’d like to create a package that would put links to the documentation website for each of the main guides.  The links would be able to grab the language from the OS and use that to point the person to the proper language, automatically.

We kinda already do this for the Release Notes although the text is included in the package.  I’m not good at javascript and I’m hoping someone can help me make this happen.

Thanks!

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

Downstream of Fedora Documentation input

Are you a user of Fedora documentation?

Do you morph that documentation into something new and different?

Do you utilize the documentation for other purposes other than for your own personal use?

If you answered yes to any of those questions I’d like to hear from you!  Please send me an email (sparks@fedoraproject.org) telling me what documentation you use and how you use it if you’ve changed it into something different or used part of the documentation for other documentation.

I’m working on an article for the Fedora Marketing Team and need your input!

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

FAD (Hackfest) @ SELF – Day 1 (Friday)

Today at the Fedora Activity Day hackfest at Southeast LinuxFest we had planned on cleaning up the Fedora wiki but got side tracked working on the Docs Project wiki pages.  It wasn’t just the wiki pages that got a review but rather a lot of the contributor processes as well.

So here’s what was changed…  First the initial wiki page of the Docs Project has been simplified to better cater to the user in search of information.  We have also simplified the process for joining the Docs Project.  There are lots more goodies coming, too, but we ran out of time.  I’ll continue to work on these pages tonight.

If you’d like to see the “source” of our work, made from the discussions that ensued, you may view the pictures.

Thanks to all who participated!

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