Interview with Rich Bowen
Write a Better FM. Read The F* Manual? Maybe you need to write a better f* manual
Rich Bowen will give a talk about Write a Better FM. Read The F* Manual? Maybe you need to write a better f* manual at FOSDEM 2017.
Q: Could you briefly introduce yourself?
I’m Rich Bowen. I’ve been doing Free and Open Source software since before people made that distinction. I’ve been involved in several large projects - Perl, Apache httpd, PHP, WordPress - as well as innumerable smaller ones. And I’ve primarily worked on the documentation side of things in each of those projects, with a particular emphasis on making these products more accessible to beginners.
Q: What will your talk be about, exactly? Why this topic?
My talk is about how your community culture is a critical part of your documentation story. If you are kind and welcoming, then your community will attract people who make the project a fun place to be. But if you are impatient and dismissive of beginners, over time you’ll build a community that is a hostile, tense place, and eventually nobody will want to come play with you.
In my time working in Free Software, I’ve encountered many people who treat beginners as the enemy, or, at least, less worthy of time than anybody else. And I’ve watched this lead to the death of those communities, as attrition isn’t replaced by new blood.
FOSDEM is one of the conferences where you see the next generation of developers coming to see what’s happening, and it’s a great place to try to instill the passion for community development. While this talk is definitely about documentation, it’s also about culture, attitude, and community.
Q: What do you hope to accomplish by giving this talk? What do you expect?
I hope to open some eyes to the importance of compassion. A lot of our software communities are so focused on excellence in programming (as, of course, they should be!) that they lose sight of the human aspect of communities. A reminder of the humans at the other end of the email can often lead to more welcoming communities. And more welcoming communities lead to community growth, increased community diversity, and the influx of new ideas. Meanwhile, hostile communities lead to ever more hostile communities, which lead to project extinction.
Q: What are some examples of pitfalls in project documentation?
Documentation written by and for experts leads to newcomers feeling confused and left out of the conversation. Nobody’s got time for that, and so this often leads to these beginners giving up and selecting an alternative solution to their problems. Because, for the most part, people just want to solve problems. They are not going to care about your project unless your project cares about them, and helps them solve those problems.
And because the tone of the documentation is a direct mirror of the tone of your community, I’ve chosen, in this talk, to focus on the two things as though they are in fact the same thing.
Q: What kind of person do you have to be and what skills do you need to become a good documentation writer?
Well, writing documentation is the cross section of a number of skills.
You need to understand the software itself. You need to understand what kind of problems people are trying to solve with the software, which involves being able to listen patiently to other people, ask the right questions, and keep good notes of what they say.
And you need to have a firm grasp of language (usually, but not always, English), and an ability to clearly communicate concepts in such a way that it’s understandable by both the beginner and the expert.
You also need to take criticism very, very well, because you’re going to get it. When a software project is making code changed every day, the documentation is always a little out of date, and the users will tell you that, often in frustrated and unkind ways. You need to be patient, and not take that personally. You need to be willing to acknowledge that the docs can be improved, and that the ultimate goal of documentation is solving your users’ problems.
Q: Writing documentation doesn’t seem to be a very popular task. Why is that, do you think? And how can we attract more people to write documentation for open source projects?
Ah, here’s where I must disagree with you. Writing documentation is a HUGELY popular task. You only have to look at the thousands of third-party websites giving bad advice about your project to see that. I think that we make it too hard to participate in writing the actual documentation, and so they write docs on their blogs, on Stack Overflow, on their own howto websites, and so on. A lot of these docs are valuable and helpful, but because they’re a step removed from the software project itself, they are often promoting “worst practice” solutions, deprecated features and inefficient solutions.
The question, then, is how we get those people to become part of the documentation community of the project itself, rather than going off and writing their own websites. We need to go out and proactively welcome these people into our documentation projects, and we need to make our documentation processes more accessible to people who know the material.
On every one of the projects that I’ve been involved with, the third-party documentation vastly outweighs the “official” documentation. It’s a question of tracking down the good ones, and inviting them to join us upstream.
Q: Suppose I’m one of the core developers of an open source project without any good documentation and we have decided to do something about it. Where do we start? What should we do to get good documentation for our project? Is there some kind of roadmap we could follow?
Well, step one is to come to my talk! ;-)
But, seriously, I recommend finding your users, who are asking and answering questions on Stack Overflow, on the mailing lists, on the third-party forums. Identify who the self-made experts are. Ask them if you can incorporate their answers into your documentation as a starting point. And invite them to come join you upstream.
Give them the same rights (commit, voting, discussion, respect) that you give the people writing the code. Don’t treat them as “just the docs guy” but understand that the docs are as important as the code. (This can be hard for us to get our minds around!)
Encourage them to ask questions, and answer them patiently and thoroughly, and repeatedly. Review what they write, and make suggestions and corrections.
And, I’ll repeat, because it’s so important: Give them the same level of respect and attribution that you give to the folks writing the code.
Q: Have you enjoyed previous FOSDEM editions?
This will be my fourth FOSDEM. The first one I went to was completely overwhelming! It’s so large, both in physical size and in content breadth, that it’s hard to get your mind around it. But I’ve settled in, and greatly enjoy the event now that I understand it more.
To people that have never been to FOSDEM, I encourage you to come with an open mind, and just prepare to be a little overwhelmed. Spend a lot of time looking at the schedule before you arrive, so that you know what’s available. But also be prepared to follow your nose when you get here, and try out the vast menu of options. Take a taste of all of the different tracks and devrooms, and attend as many of the social events as you possibly can. There’s just so much going on, you can’t avoid missing most of it, but don’t make the mistake of getting stuck in one room the entire event and missing out on the rich variety of content, people, projects, and experiences.
And come see me at the CentOS booth, or the Apache booth, or the OpenStack booth - I’ll be flitting around myself - if you want to talk more about anything I’ve said in my remarks, or in my talk.
Creative Commons License
This interview is licensed under a Creative Commons Attribution 2.0 Belgium License.