Open Books    Posted:

The Fedora Docs team is comprised of a small group of very talented professional technical writers, and a handful of community writers like myself. The group recently met [1] to discuss recent and upcoming changes in the distribution, revamp how we help new contributors get started, and take a close look at how we interact with the Fedora community.

The FAD was attended in person by a few folks meeting in Raleigh and a few in Brno, with others participating remotely from around the world. Besides discussing recruitment and training, we continued work on a new publishing backend that will eventually replace the terminally bloated web.git [2] currently in use.

the learning book

The Fedora Documentation Guide [3] received an overhaul. The book that once contained brief overviews of common docs tasks has now been expanded substantially. The Guide will soon feature a comprehensive introduction to DocBook, Publican, and git, based on Jared Smith's excellent presentations on the subject. The new and curious will be able to follow along with the guide using the "docs-beginner" [4] guide, a workbook corollary to the writing course.

In addition to the writers' training, the book has also grown a style section and an introduction to the community. We've found that new contributors can become too focused on the tooling and procedures; they get discouraged before writing much, or forget there are friends to help.

the cookbook

The complaint I hear most often from potential contributors ( besides the unfamiliar tooling & markup ) is that they don't know what to start writing about, or they have an idea for a short tutorial but don't know where to put it. The official guides [5] don't have a place for everything, and starting a new guide is a daunting task.

This is the primary problem I wanted to address at the FAD. We needed to find a way to help people write and publish short, autonomous articles. The solution had to be something approachable but still meet our high quality standards. It had to be something that would play nice with Transifex for translation. To be distributed, it needed static HTML with minimal maintenance requirements.

The answer we settled on is what will become the Fedora Cookbook [6], and it is a process as much as a book. Anyone can submit a 'recipe' for the Cookbook - currently to - using provided templates [7], and Docs volunteers will review, mark up, submit for translation, and publish. You're welcome to participate and learn as much or as little of that process as you like.

book in progress

To glue all this together, there's a mentorship [8] program inspired by Fedora Infrastructure's fi-apprentice program. There are some very knowledgeable folks to help with research, writing technique, markup, asynchronous bantering, whatever. Your mentor can walk you through the docs-beginners guide to a running start at the cookbook, or help with whatever you're interested in.

If you'd like to participate in the mentorship program or chat with the Docs team, stop in to #fedora-docs [9] during the newly instituted office hours. fedocal [10] will soon show blocks of time where we have committed to be available to the community.

The Docs team has been following along with, the different working groups, and the future of the distribution, of course. We haven't taken action, though; documentation is inherently reactive, and things haven't settled out enough to document.

During the FAD, we discussed our strategy for documenting Products and decided that waiting for the various working groups to define and request a documentation product wasn't the best approach. We have volunteers to track the product workgroups, and plans to compare notes regularly. I have volunteered to work with the Workstations group; the others will be introducing themselves soon if they haven't already.



immanetize blog!    Posted:

the static site generator

After trying a number of FLOSS CMS projects, I've settled on Nikola [1]. It's simple to manage, easy to write for, supports translation ie Transifex [2], and static HTML means low server overhead and decreased attack surface.

Nikola is a very active project, with frequent releases for bugfixes and cool new features. I'm writing in ReStructuredText [3], familiar to most from GitHub by now, but there is support for a wide variety of source formats. Overall, I'm very happy with it so far, and there's a ton of features I haven't investigated yet.

the pushing of bits

To manage the content and the site template, git comes in to play (and let's be honest, I default to using git for everything at this point.) Nikola very nicely separates content from structure and presentation, so you can use separate repos; useful for a group that wants to have different permissions for each.

I've deployed the site to a vps [4] using ansible, including command-locked ssh keys to refresh content via cron jobs. Admittedly, that's probably overkill for a personal blog, but it's comforting to know that the effort required to deploy an updated site isn't much more than git merge production;git push --all. Migration to another VPS would be as simple as changing the target of a playbook and running it.

the composition of content

Content has always been the hard part for me. I can write howtos for procedures, like what's being used for this site (and you probably will see that howto, soon!) To publicly opine is a different story, though. As much as I appreciate constructive criticism, I've never been a big fan of unsolicited advice. As my community involvement has increased, however, I see the role of such things. There's a lot to be learned from the folks sharing on sites like Fedora Planet [5].

the ulterior motive

Put simply, search ranking. Not in the way you're thinking, though; I'm not after referral revenue or pride of place at the top of Google results. It's always bothered me to search for technical information only to find linkbait and outdated or even horribly ill-advised content.

It's become more than a pet peeve since joining Fedora Docs - our site's [6] search visibility is about that of an equatorial noontime shadow. If you're explicitly looking for it, you'll get results from there; if not, you'll find someone that tells you how to disable SELinux, set your vhost directory to 0777, or even obtain proprietary software from questionable sources. Yyeachk.

With some luck, my postings will give visibility to others' sites, that have quality solutions following solid best practices.

[1]A python static site generator:
[2]The translation platform used by Fedora, Fedora Docs:
[3]A simple plain text markup specification:
[4]My provider of choice just happens to be operated by a friend from Fedora:
[5]A site aggregating blogs from the Fedora community:
[6]Very comprehensive guides for Fedora: