Open Communities and Support    Posted:


I wasn't a student of collaborative methodologies or a dedicated open source enthusiast when I began my relationship with Fedora. I wanted to learn to use the software, got help from the community, and wanted to return the favor. Some of you might remember those early efforts, and justly commend yourselves on your patience :)

In the intervening years, I've learned a lot more than I set out to. There's a culture in the Fedora community that's consistently offering a hand up, guiding towards better understanding, and iteratively improving for all.

Support Communities

Tech support has become a ubiquitous part of modern society. I think everyone's gone through the frustrating process of trying their best to make something work, giving in, and calling the toll-free number on the box for rote instructions.

In open source support venues such as #fedora, Ask Fedora, or various mailing lists, I found people offering assistance not out of obligation, but out of passion. There are no designated roles; sometimes you get help, sometimes you provide it. You might get very direct assistance, or discover a completely different approach to your problem that's much more effective.

People in Support

The most impressive aspect of this relationship to me is the attitude of the participants. Assertive or even coarse personalities accept and welcome correction of their statements, and discourse largely revolves around the merit of the ideas communicated. Because the conversations are accessible to all, everyone has the opportunity to benefit from answers to questions they've never thought to ask. I've gathered a lot of best-practices habits from reading mailing lists.

The take-home axiom from today's post is that the best way to learn is to teach - and the open nature of Fedora's support community not only proves it, but it affords us the opportunity to be taught while we teach, and about our teaching, and so on. These groups have grown their own continuous improvement mechanisms.

Enabling and onboarding users

To an open source project, a thriving support community offers more than just user satisfaction. It provides valuable feedback on the usability of your products, directly and by inference. With experienced contributors in the mix, contribution opportunities and community roles can be paired with individuals with particular skills. An IRC channel can serve as a recruiting station, simply by demonstrating the tenor of the community.

For a small project, this is easy; the developers communicate with each other over some medium, and make that communication channel available to their users. As a project grows, the development discussions begin to confuse or obscure the user questions, so another channel is used. This progression leads to the user channel serving itself, with expert users fielding questions from novices. The immediate user concerns are better served, but there's a loss of the tight sense of community that comes from talking directly with the developers.


How you think Fedora's user support lists and IRC channels can improve the user/developer feedback loop, and better catalyze new contributors? Comment and share!

Comments

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

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: http://getnikola.com/
[2]The translation platform used by Fedora, Fedora Docs: https://www.transifex.com
[3]A simple plain text markup specification: http://docutils.sourceforge.net/docs/user/rst/quickref.html
[4]My provider of choice just happens to be operated by a friend from Fedora: http://prgmr.com/xen/
[5]A site aggregating blogs from the Fedora community: http://planet.fedoraproject.org/
[6]Very comprehensive guides for Fedora: https://docs.fedoraproject.org

Comments

Share