incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jean Weber <jeanwe...@gmail.com>
Subject Re: I'd love your opinion on a question of FAQ style
Date Wed, 14 Mar 2012 04:00:51 GMT
(Sorry about the broken thread. I plucked this out of the archives.)

Rob,
Not commenting on the level of detail, just on the presentation.
Thirty years of writing and editing user documentation, FAQs, etc, and
ten+ years of website work has taught me this:
* Bullet lists, preferably of no more than one sentence per item, are
MUCH easier for readers to digest than paragraphs of information.
* People scan; they don't read paragraphs unless they absolutely must.
* Put the most important info in the first few words of any sentence
or bullet item, when possible; again for ease of scanning.

--Jean


Rob Weir wrote,

This question came up on the other thread.  I'd be interested in
knowing which style of FAQ you prefer:

Example A:

"Who is building Apache OpenOffice releases?

 * In common with other Apache projects, work on Apache OpenOffice is
performed by individual volunteers.
 * Development is done a number of the original developers of
OpenOffice.org in addition to community volunteers and developers from
other projects derived from the OpenOffice codebase including IBM
Symphony."

or Example B:

"Who is developing Apache OpenOffice?

Like any other Apache project, work on Apache OpenOffice is performed
by a diverse group of volunteers, from over a dozen countries.  We
have participants who are brand new to the project as of last week.
We also have many old hands, who have been involved with OpenOffice
for a decade or more.  These volunteers work on coding, testing,
documentation, websites, translations, marketing as well as other
functions.  Some of our volunteers are listed here:
http://incubator.apache.org/openofficeorg/people.html.    If you are
interested in helping develop the next great version of Apache
OpenOffice please take a look at our Getting Involved page
(http://incubator.apache.org/openofficeorg/get-involved.html)."

[other examples snipped]

These two approaches, A and B, differ in tone, formality and
information level.   Which do you think would be most useful to users
seeking answers to their questions?

-Rob

Mime
View raw message