incubator-ooo-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Lohmaier <cl...@openoffice.org>
Subject Re: I'd love your opinion on a question of FAQ style
Date Wed, 14 Mar 2012 04:56:17 GMT
On Wed, Mar 14, 2012 at 4:00 AM, Rob Weir <robweir@apache.org> 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."

+1

> or Example B:
>
> "Who is developing Apache OpenOffice?
>
> [...]

tl;dr

Definitely A for a FAQ list.

> Another set:
>
> Example A:
>
> "Where can I get updates to the copy of OpenOffice.org that I am running?
>
>   *  There have been no updates to OpenOffice.org binaries released
> for users since Oracle stopped development and there will be no
> patches to those earlier binary programs released.
>    * The project is currently preparing a new version of the code and
> it will be available through the openoffice.org website.
>    * Once Apache OpenOffice v3.4 is released, the project recommends
> you replace your OpenOffice.org installation with it.
>    * Again, there are developer versions available for testing purposes."
>
>
> and
>
> Example B:
>
> "Where can I get updates to the copy of OpenOffice.org that I am running?
>
>  * The latest release of OpenOffice.org is 3.3.  If you have that then
> you have the latest.  If you would like to extend the capabilities of
> your OpenOffice 3.3 you might take a look at the many compatible
> extensions (http://extensions.services.openoffice.org/) and templates
> (http://templates.services.openoffice.org/)  that are available.

Don't see the relevance of extensions and templates for getting
updates to OOo - and hard to make a decision on style when the content
is what makes most of the difference.

> *   We are currently preparing a new release, Apache OpenOffice 3.4.
> When available, you can download it from the http://www.openoffice.org
> website.  If you want to be on a notification list for when Apache
> OpenOffice 3.4 is available for download, you can send an email to
> ooo-announce-subscribe@incubator.apache.org."
>
> These two approaches, A and B, differ in tone, formality and
> information level.

So you say it yourself. You don't ask about style, but mix in
information level.  So your way of asking that question is flawed to
begin with.
Whether to add this or that bit of information to the answer of a faq,
or what faqs to put there in the first place is a completely different
topic from the style used.

>  Which do you think would be most useful to users
> seeking answers to their questions?

definitely A. Concise, straight to the point, easy to scan.

It is a FAQ, I want to get the answers quickly. I don't want to read
nice prose or marketing - I want clear statements.

That being said: Adding additional info like the "subscribe to not
miss the new release" or updates for extensions and templates can be
obtained from the respective repositories" is a different question.
But that should not be in the very same bullet point as the actual
answer.

KISS - that's the style to aim for when writing a FAQ. The FAQ is also
likely to be visited by non-english speakers, so using whatever
elaborate language is not helpful in understanding anyway.

* simple
* concise
* easy to parse

ciao
Christian

---------------------------------------------------------------------
To unsubscribe, e-mail: ooo-users-unsubscribe@incubator.apache.org
For additional commands, e-mail: ooo-users-help@incubator.apache.org


Mime
View raw message