[FM Discuss] Don't Flip: A Guide to Gathering and Writing Useful Documentation

[Andy Oram]

The need for a book about how to write a book came up yesterday among the
FLOSS Manuals volunteers who are meeting this week at Winter Camp in
Amsterdam. Adam Hyde asked me to start a proposal that we can all
refine and then publish to recruit potential authors. I probably spent
more time on the proposed title than anything else. Here is a draft of
an announcement (which we can all blog, etc.) and an outline. Comments
on all aspects of the project are welcome.

Andy

----

Announcement

Don't Flip: A Guide to Gathering and Writing Useful Documentation

FLOSS Manuals brings together people who care about freedom and free
software to produce documentation that can help people around the
world use technology to achieve their goals. During a recent meeting
of volunteers, we realized it would be useful to have book about how
to create a book.

There are shelves' worth of textbooks and professional guides for
technical writing, but none that we've found focuses on the needs
experienced by today's online communities or takes into account the
new technologies and social environments of online information
production. These communities and environments are squarely at the
center of "Don't Flip."

The tentative subtitle, "A Guide to Gathering and Writing Useful
Documentation," emphasizes that FLOSS Manuals is a collaborative
organization. We gather as well as write; we want many people to
contribute and keep documents current.

And we're extending this principle peer production to our new
how-to-write-a-book project. We're looking for people to contribute
tips and guidelines from their own experience.

At the same time, we plan to apply the best standards that leading
project members have developed over decades of writing
experience. While recognizing the existence of different needs and
learning styles, will demand the best from our books and assiduously
weed out the bad habits that computer documentation has suffered from
since its beginning.

To keep the book accessibly and spry, we'd like to supplement the
usual examples from computer documentation with examples from everyday
activities that may appeal to a wide variety of readers: cooking,
gardening, sewing, bicycle repair, home maintenance, etc.

A tentative outline has been posted at:

  http://en.flossmanuals.net/bin/view/FLOSSManuals/DontFlipOutline

You can start right now by adding sections and suggesting changes. If
you want to make a major contribution, please contact ...