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

[Andy Oram]

Yes, Ed, wonderful post--these are central questions when trying to teach people, and that includes writing for them. Not only is the truth hidden, but the fact that it is hidden is hidden.

Many people turn to a book because they don't know what search terms to enter into search engines, and don't know how to ask questions. Books should help them become informed researchers. These questions are not simple, and they will always be a challenge. Let's certainly talk about it in this book. I won't have time to edit the outline until after the FSF book sprint March 21-22, but you can try working them in.

Andy

------

...

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?