Open Books


Posted:   |   More posts about fedora documentation community

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 docs-qa@lists.fedoraproject.org - 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.

book.next

The Docs team has been following along with Fedora.next, 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.

[1]https://fedoraproject.org/wiki/Docs_FAD_2014
[2]https://git.fedorahosted.org/cgit/docs/web.git
[3]https://git.fedorahosted.org/cgit/docs/documentation-guide.git
[4]https://git.fedorahosted.org/cgit/docs/docs-beginner.git
[5]https://docs.fedoraproject.org
[6]https://git.fedorahosted.org/cgit/docs/fedora-cookbook.git
[7]https://git.fedorahosted.org/cgit/docs/fedora-cookbook.git/tree/en-US/examples
[8]https://fedoraproject.org/wiki/Docs_Project_mentors
[9]http://webchat.freenode.net/
[10]https://apps.fedoraproject.org/calendar/
Comments powered by Disqus
Share