openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi all,

We had a great discussion at the Design Summit about documentation
processes and how difficult it is to become a doc contributor and keep the
docs accurate.

As promised, I dug up the fascinating McGill University study about open
source doc projects. They found that you shouldn't separate doc process too
far from coding process. I've attached the PDF. Would love to hear your
feedback and applications for OpenStack.

Some excerpts from the PDF:
"We conducted an exploratory study to learn more about
the documentation process of open source projects. Specifically,
we were interested in identifying the documentation
decisions made by open source contributors, the context in
which these decisions were made, and the consequences these
decisions had on the project. We performed semi-structured
interviews with 22 developers or technical writers who wrote
or read the documentation of open source projects. In parallel,
we manually inspected more than 1500 revisions of 19
documents selected from 10 open source projects."

"The programming language of the projects varied
greatly: Perl (2 contributors), Java (2), Javascript (1), C(2),
C++ (1), PHP (2), Python (2). The age of the projects
ranged from 1.5 years to more than 15 years with an average
of 8.7 years."

"7. CONCLUSION
Developers rely on documentation to learn how to use
frameworks and libraries and to help them select the open
source technologies that can fulfi ll their requirements. Following
a qualitative study with 22 documentation contributors
and users and the analysis of the evolution of 19 documents,
we observed the decisions made by open source contributors
in the context of three production modes: initial
eff ort, incremental changes, and bursts.
Understanding how these decisions are made and what
their consequences are can help researchers devise documentation
techniques that are more suited to the documentation
process of open source projects and that alleviate the
issues we identi fied. Our fi ndings can also help practitioners
make more informed decisions. For example, a better
understanding of embarrassment-driven development could
motivate developers to document their changes quickly after
making them. A better comprehension of the relationship
between the type of project (e.g., library or framework) and
getting started and reference documentation could help contributors
focus their e ffort on the more appropriate type of
documentation."

Thoughts?

Anne
<http://is.gd/TpxZbc>

Attachment: fse2010.pdf
Description: Adobe PDF document