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

[Edward Cherlin]

On Fri, Mar 6, 2009 at 1:08 AM, Andy Oram <andyo at oreilly.com> wrote:
> 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

Thanks, Andy. I have been wishing for this book, and this opportunity.

My question of the moment is, How do you let the reader know that you
have the answers to questions the reader has not consciously
recognized yet, or has recognized but doesn't know how to ask? This
has several variations.

o How will the reader try to find information? What questions will the
reader ask, in what form?

o If the reader does not know the jargon of the field, what terms are
likely to come to mind?

o Should you index those terms even if they don't appear in the body
(with <i>see</i> links to the terms used in the book, or
disambiguations)?

o Does the reader know what the product is capable of? Or what those
capabilities are good for?

Some of the tools for addressing these questions are the ToC,
glossary, introductory sections, cross references, and index.
Sometimes it requires a little attention within content sections.
Mainly, it requires forethought and imagination. Do we understand the
reader's state of mind? Are we perhaps confusing the less-prepared
reader at some points? Can we satisfy the novice without turning off
the knowledgeable? Do we need to segment the audience, and write
differently for some than for others, perhaps in different chapters or
even separate books?

None of this is a problem if we can be sure that readers will actually
read the whole book. But they don't. (Hobbes: Did you read the
instructions? Calvin: Do I _look_ like a wimp?) In the best case, they
read the parts they think they need, on the basis of not having read
the book through. Or at all. %-[

Another version is "Defensive Documentation". When I have to work with
inadequately documented software, I often write up the procedures I
discover to share with others, who may not know of the existence of
the problem I just solved before it bites them, much less the answer.

> ----
>
> 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 ...
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>



-- 
Silent Thunder (默雷/धर्ममेघशब्दगर्ज/دھرممیگھشبدگر ج) is my name
And Children are my nation.
The Cosmos is my dwelling place, The Truth my destination.
http://earthtreasury.net/ (Edward Mokurai Cherlin)