OpenHelp Trip Report: Warren Block

Warren Block of the documentation team recently submitted his trip report for the OpenHelp Documentation Conference:

The Open Help Conference was held in Newport, Kentucky, just across the river from Cincinnati, Ohio.  Shaun McCance, the GNOME documentation team's "Fearless Leader", organized the conference to bring together open source documentation groups.  Dru Lavigne of PC-BSD asked me earlier this year to attend, and the FreeBSD Foundation graciously sponsored the trip.  Conference attendance was rather small, but as the conference went on, it turned out that a smaller group allowed for different, more personal discussions which I really enjoyed.

Several of the attendees arrived two days early to work on an open source style guide.  Trying to start a project from scratch turns out to be surprisingly difficult.  We spent a great deal of time talking about the issues that affect documentation, and particularly open source documentation.  Content issues like tense, passive or active voice, weasel words like "should", compound words, and translation all came up. How to organize such a document is a huge question also. Then there were project issues, like what license to use, where to host, what type of markup language to use, even what to call the document.  The nice thing about existing projects is that while you may not be particularly happy with the rules or decisions, you are at least freed from making all those decisions to work on actual content.  In the end, an archive was created on gitorious with a collection of some of the basic ideas.

The conference itself began with Florian Nadge of SUSE and his talk, Writing for Translation.  As an American, I can barely speak English, yet there was a lot of crossover between the concepts of writing to make translation easy, and writing for clarity.  Many of the concepts are the same: keeping sentences short, not combining multiple ideas into one sentence, avoiding things that are difficult to translate like humor and jargon.  Another interesting point was that translation teams are often the first people in a country to be introduced to software, and the same people can become valued contributors.  Several recommendations that we should add to the FreeBSD documentation Primer include active voice, consistent words for the same meaning, and keeping sentences to less than 23 words.

I followed with my presentation on automated documentation proofreading with igor (textproc/igor).  The concept of making documentation easier to write by having the computer proofread everything that can be automated is a surprising idea to some people.  As usual, people were fascinated with features that seemed simple to me, and vice versa.  This is one of the best reasons for these conferences: the cross-pollination of ideas.

Next up were a series of shorter talks on tools.  Janet Swisher of Mozilla gave a demonstration of Popcorn Maker, an HTML5 Javascript library from http://popcornjs.org/ that allows integrating video into documentation.  The really clever part of this is that it can use existing video without any changes, tying a particular point in a video to a link in documentation, or the other way around.

Anne Gentle of OpenStack talked about Clouddocs Maven, a web-based documentation system.  Shaun McCance spoke on ITS Tool, a program that assists in translating XML with PO files.  It is in FreeBSD ports as textproc/itstool.

The second day of the conference had more usable information.  Jean Weber of the LibreOffice documentation team discussed how they produce documentation with a very small team of diverse contributors.  Florian Nadge spoke about Publican, the Red Hat DocBook XML toolchain.

Shaun McCance gave another presentation, this time on making documentation accessible for people with differing physical abilities. As with the other talks, there were surprising crossovers.  For instance, help systems that require a mouse are unusable for people with limited movement, but also on a factory floor where there is no place to put a mouse.  Audio and video help face similar restrictions.

After the presentations, the group had a series of far-ranging talks covering such subjects as how to encourage users to become contributors, how to encourage under-represented groups to become involved in open source, and how to reward and retain contributors.

Finally, on Monday, Dru and I participated in a doc sprint.  We covered use of some of the FreeBSD documentation tools, and took and closed a PR as an example.  She documented--and I occasionally helped identify--the packages needed to run Publican on FreeBSD.  Since then, Steve Wills created a full port, textproc/publican.

The conference was a great experience.  As a side note, Newport and Cincinnati were great towns.

My thanks to Dru Lavigne for inviting me, Shaun McCance for hosting the conference, all the attendees for their participation, and particularly the FreeBSD Foundation for making it possible for me to attend.

BSDCan Trip Reports: Hiren Panchasara and Adrian Chadd

The last of the BSDCan trip reports have been received. Hiren Panchasara posted his on his blog. Adrian Chadd's report is as follows:

The last couple of years has seen me take stewardship of the net80211 stack and Atheros wifi driver development and maintenance. The FreeBSD Foundation provided me with a travel grant to enable me to participate in the BSDCan 2012 developer summit and conference as the wireless stack maintainer. For this I am very grateful.

I split my time between attending events and talking with people about networking and wireless in general. I even had a few developers come up to me and ask for some assistance in debugging their particular wireless problem. Everyone seemed very happy that the wireless subsystem was being actively developed again by myself and the other volunteers, which unfortunately couldn't make it to BSDCan.

I presented a wireless update during the developer summit, which was well received. Although the focus was FreeBSD, the progress being made in the other BSDs has been very impressive. OpenBSD in particular has made great strides in porting wireless drivers from Linux and other sources. It was a shame that there wasn't a strong presence from OpenBSD this year as I'd have loved to discuss this with them.

It was good putting names to faces. David Italiano and I had been talking online about PMC and MIPS related things. Alexander Motin and I had some brief discussions about time-keeping with his new tick management system, and some of the challenges faced with ACPI and MIPS. Most importantly (for me) was to meet Stefan Bethke, who had been working on the ethernet switch support in FreeBSD. We committed the work to FreeBSD-current during the course of the conference so that the code was in the tree and available by the time he gave his BSDCan presentation. I worked with Justin Hibbits on trying to identify endian problems in one of the wireless drivers (since he develops on PPC platforms) and provided him with an Atheros NIC which does work on PPC. I hope to continue working with all of these people and more in the future.

The networking discussions during the developers summit was of particular interest. Wireless support provides many challenges to a network stack design, both in terms of locking and in terms of queue management. Wireless devices are also approaching and exceeding gigabit-per-second speeds and this puts them on par with the traditional, ethernet style networking. I provided some feedback during the mbuf and multi-queue redesign discussions which I hope will see FreeBSD continue to maintain high-quality and high-performing wireless support now and in the future. The usual suspects were there (Robert Watson, John Baldwin) and it was good to bounce ideas off of them.

I also found the vendor summit quite inspiring. The turnout was fantastic and many, many vendor representatives had a lot to say -both positive things about the current supported features as well as providing excellent suggestions for new features. Although the wireless side of things was woefully under-represented (I believe I was the only active wireless representative there) I hope to help change this in the future. George kept writing down blackboards full of ideas and for a while I wondered when the ideas and brainstorming would stop. All in all, a very positive and reassuring event.

I am very thankful for the FreeBSD Foundation to provide me with the means to participate in this year's BSDCan. I look forward to participating next year.

Accepting Travel Grant Applications for EuroBSDCon 2012

Calling all FreeBSD developers needing assistance with travel expenses to EuroBSDCon 2012.

The FreeBSD Foundation will be providing a limited number of travel grants to individuals requesting assistance. Please fill out and submit  the Travel Grant Request Application by September 19, 2012 to apply for this grant.

This program is open to FreeBSD developers of all sorts (kernel hackers,  documentation authors, bugbusters, system administrators, etc).  In some  cases we are also able to fund non-developers, such as active community members and FreeBSD advocates.

You request funding based on a realistic and economical estimate of travel costs (economy airfare, trainfare, ...), accommodations (conference hotel and sharing a room), and registration or tutorial fees.  If there are other sponsors willing to cover costs, such as your employer or the conference, we prefer you talk to them first, as our budget is limited.  We are happy to split costs with you or another sponsor, such as just covering airfare or board. If you are a speaker at the conference, we expect the conference to cover your travel costs, and will most likely not approve your direct request to us.

We review your application and if approved, authorize you to seek reimbursement up to a limit.  We consider several factors, including our overall and per-event budgets, and (quite importantly) the benefit to the community by funding your travel.

Most rejected applications are rejected because of an over-all limit on travel budget for the event or year, due to unrealistic or uneconomical costing, or because there is an unclear or unconvincing argument that funding the applicant will directly benefit the FreeBSD Project. Please take these points into consideration when writing your application.

We reimburse costs based on actuals (receipts), and by check or bank transfer. And, we do not cover your costs if you end up having to cancel your trip. We require you to submit a report on your trip, which we may show to current or potential sponsors, post on our blog, and include in our semi-annual newsletter.

There's some flexibility in the mechanism, so talk to us if something about the model doesn't quite work for you or if you have any questions. The travel grant program is one of the most effective ways we can spend money to help support the FreeBSD Project, as it helps developers get together in the same place at the same time, and helps advertise and advocate FreeBSD in the larger community.

FreeBSD Foundation's Semi-Annual Newsletter

We are pleased to announce the publication of The FreeBSD Foundation's 2012 Semi-Annual Newsletter.

The newsletter begins with the letter from the President, "An Unsatisfied Market", where Justin Gibbs discusses the goal of a credible marketplace offering FreeBSD support and services.

Development project updates are provided by the developers for the  NAND Flash Support,  Growing Filesystems Online, auditdistd, IPv6 Performance Analysis, Capsicum Component Framework, and iSCSI Scoping projects.


Conference updates are provided by the organizers of the BSDCan 2012,  AsiaBSDCon 2012, BSD-Day 2012, Ottawa Developer Summit 2012, and Ottawa Vendor Summit 2012 conferences and summits.

The newsletter also includes  FreeBSD research highlights, the Grant and Travel Grant Recipients for the first half of 2012, a company testimonial from A-Team Systems, and the
links to the Foundations' 2012 Q1-Q2 Profit/Loss and 2012 Q1-Q2 Balance Sheet.