-
Notifications
You must be signed in to change notification settings - Fork 33
/
ShaunMcCance.tex
123 lines (103 loc) · 6.8 KB
/
ShaunMcCance.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
\chapterwithauthor{Shaun McCance}{Stop Worrying and Love the Crowd}
\authorbio{Shaun McCance has been involved in GNOME documentation since 2003
as a writer, community leader, and tool developer. He has spent
most of that time wondering how to get more people to write better
documentation, with some success along the way. He offers his
experience in community documentation through his consulting
company, Syllogist.}
\noindent{}Something big happened as I was preparing to write this: GNOME 3 was released.
This was the first major GNOME release in nine years. Everything was different,
and all of the existing documentation had to be rewritten. At the same time, we
were changing the way we write documentation. We had thrown away our old manuals
and started fresh with dynamic, topic-oriented help using Mallard.
A few weeks before the release, a group of us got together to work on the
documentation. We worked all day, planning, writing, and revising. We wrote
hundreds of pages against a moving target of late-cycle software changes. We
had people contributing remotely, submitting new pages and correcting existing
content. It was the most productive I had ever seen our documentation team.
What did we finally get right? A lot of factors came together, and I could
write an entire book about all the nuances of Open Source documentation.
But the most important thing I did was get out of the way and let others
do the work. I learned to delegate, and to delegate the right way.
Rewind eight years. I began to get involved with GNOME documentation in 2003.
I did not have any real experience as a technical writer at the time. My day
job had me working on publications tools, and I started working on the tools
and help viewer used for GNOME documentation. It was not long before I was
pulled into writing.
In those days, much of our documentation was handled by professional tech
writers inside Sun. They would take on a manual, write it, review it, and
commit it to our CVS repository. We could all look at it after the fact,
learn from it, and make corrections to it. But there was no concerted
effort to involve people in the writing process.
It is not that the Sun writers were trying to be protective or hide things
behind closed doors. These were professional tech writers. They knew how
to do their job. They were good at it. Other people could take on other
manuals, but they would write their assignments the way they knew how.
Running each page by a group of untrained contributors, however
enthusiastic, is inviting the very worst kind of bikeshedding\footnote{\url{https://secure.wikimedia.org/wiktionary/en/wiki/bikeshedding}}
imaginable. It is just not productive.
Inevitably, the winds shifted inside Sun and their tech writers were
assigned to other projects. That left us without our most prolific
and knowledgeable writers. Worse than that, we were left with no
community, nobody to pick up the pieces.
There are ideas and processes that are standard in the corporate world.
I have worked in the corporate world. I do not think anybody questions
these ideas. People do their job. They take assignments and finish them.
They ask others for reviews, but they do not farm out their work to
newcomers and less experienced writers. The best writers will probably
write the most.
These are all really obvious ideas, and they fail miserably in a community-based
project. You will never develop a community of contributors if you do everything
yourself. In a software project, you might get contributors who are skilled and
persistent enough to contribute. In documentation, that almost never happens.
Most people who try to contribute to documentation do not do it because they
want to be tech writers, or even because they love to write. They do it
because they want to contribute, and documentation is the only way they
think they know how. They do not know how to code. They are not good at
graphic design. They are not fluent enough in another language to translate.
But they know how to write.
This is where professional writers roll their eyes. The fact that you are
literate does not mean you can write effective user documentation. It is
not just about putting words on paper. You need to understand your users,
what they know, what they want, where they are looking. You need to know
how to present information in a way they will understand, and where to put
it so they will actually find it.
Tech writers will tell you that tech writing is not something just anybody
can do. They are right. And that is exactly why the most important thing
professional writers can do for the community is not write.
The key to building a successful documentation community is to let others
make the decisions, do the work, and own the results. It is not enough to
just give them busy work. The only way they will care enough to stick around
is if they are personally invested. A sense of ownership is a powerful
motivator.
But if you only get inexperienced writers, and you hand all the work
over to them, how can you ensure you create quality documentation?
Uncontrolled crowd-sourcing does not create good results. The role
of an experienced writer in a community is as a teacher and mentor.
You have to teach them to write.
Start by involving people early in the planning. Always plan from the
bottom up. Top-down planning is not conducive to collaboration. It is
hard to involve people in crafting a high-level overview when not
everybody has the same sense of what goes into that overview. But
people can think of the pieces. They can think about individual topics
to write, tasks people perform, problems people have, questions people
ask. They can look at forums and mailing lists to see what users ask.
Write a few pages yourself. It gives people something to imitate. Then
dish out everything else. Let other people own topics, or entire groups
of topics. Make it clear what information they need to provide, but let
them write. People will learn by doing.
Be constantly available to help them out and answer questions. At least
half the time I spend on documentation is spent answering questions so
that other people can get work done. When people submit drafts, review
the drafts and discuss critiques and corrections with them. Do not just
make the corrections yourself.
This still leaves you handling the big picture. People are filling in
parts of the puzzle, but you are still putting it together. As people
get more experienced, they will naturally take bigger and bigger pieces.
Encourage people to get more involved. Give them more to do. Get them
to help you help more writers. The community will run itself.
Eight years later, GNOME has managed to create a documentation team
that runs itself, deals with problems, makes decisions, produces great
documentation, and constantly brings in new contributors. Anybody can
join in and make a difference, and that is the key to a successful Open
Source community.