(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
