Skip to content

The outside and inside of documentation, or, why aren’t you publishing on the Fedora wiki?

You may have noticed there is a larger world of free software outside of Fedora than inside.  The number of packages inside the Fedora Universe has really grown.

You may have noticed there is a larger world of Fedora-specific how-to documentation outside of Fedora than inside.  A really huge amount.  You may notice that the amount inside has grown very little by comparison.

There is new how-to documentation on the Fedora Planet nearly every day.  The Fedora Forum is full of useful (and not so useful) content.  Sub-communities such as Fedora-fr have rich document sets. People write how-to content in to their blogs, to their own wikis or CMS systems, or post downloadable content from any number of places. I just caught up on a thread on Fedora Ambassadors list about a Fedora 10 how-to document.  As cool as it the document is, as great as the effort is, I could not help my first thought.  “Why is this document not written as part of Fedora itself?”

You know, just write it and add [[Category:How to]] and [[Category:Draft documentation]] to the pages.

The irony is, it is harder to get a package in to Fedora than a document, but because of our poor documentation (compared to the Packaging Guidelines) and equally poor marketing(?), not many people are taking the step to bring Fedora content inside of Fedora.

Since there are going to be a large number of contributors handy at the upcoming FUDCon, maybe that’s a chance to talk about it.

There are some very-near-term fixes that are going to make it easier to  bring content inside of Fedora.  Then all we need is the better marketing. :)

  • Recent wiki gardening work, including page renaming and smart category usage, is yielding a useful wiki. Ian Weller, myself, and others are going to be swinging the wiki hammer at FUDConF11, and it’s much more than learning about the markup.  There are real and useful best practices that yield you a useful set of wiki content.  Looked at the Fonts SIG pages lately?  That’s one way to do it.  Hopefully I’ll be showing off the newly trimmed, renamed, and categorized Docs Project pages at FUDCon.
  • Better localization for the wiki — a wiki per native-language means people can include locale-specific content as well as content translated from the main English wiki.  What would help more here is a way to track when new pages are created in native-language wikis that do not correspond to one from the English wiki.  This flags those pages as possibly worthy of translation to other languages, including English.
  • A content management system.  I’ve been talking about this for a while, and hope that FUDCon helps move the needle on this activity.  This helps by distributing publishing rights to the teams who own the content — the writing teams, the SIGs, and the other sub-projects.  By having content more tied to Fedora versions, it make it easier on writers who only want to maintain content for a specific version of Fedora.
  • This all makes using DocBook XML much easier for everyone.  We’ve already had a boost from the relative ease of using Publican.  By hosting each guide as a separate project on fedorahosted.org, the onus and accountability is firmly in the writing team and not blocked by project administrators.  This was how we rolled for Fedora 10 in doing the Installation Guide and Release Notes — task tracking with Trac and  project management from within the team.  When that content is using an installable, upstream maintained system such as Publican surrounded by standard processes, we are much farther in the goal of creating a useful, repeatable documentation process that can be borrowed from Fedora and used in other places.

If you are writing content that really could or should be on the Fedora wiki, please join the wiki mailing list and find out how to do it right.