incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <robw...@apache.org>
Subject Re: Clarifying facts
Date Wed, 14 Mar 2012 02:36:31 GMT
On Tue, Mar 13, 2012 at 10:14 PM, Simon Phipps <simon@webmink.com> wrote:
>
> On 14 Mar 2012, at 01:35, Rob Weir wrote:
>>
>> Allowing a few more brushes in there is a great idea.
>
> You've made quite a few edits I see - thanks.
>

6 to be exact.

> With respect, I think you are making it rather verbose and losing the easy-to-read bulleted
approach.
> You are also introducing a style that external readers will consider to be interpreting
the facts.
>

Of course we're going to interpret facts.  That is one way in which we
are helpful for users.  And remember, your start was hardly neutral.
The choice even of what questions to ask, and which ones not to ask,
is also an editorial judgment, and one that comes with a point of
view.

> Perhaps a link to the forums Tutorials page.
>

Something to keep in mind is that we already have several FAQ's for the project.

We have Community, Developer and PPMC FAQs here:

http://incubator.apache.org/openofficeorg/community-faqs.html
http://incubator.apache.org/openofficeorg/developer-faqs.html
http://incubator.apache.org/openofficeorg/ppmc-faqs.html

And we have a much larger set of FAQ's, mostly product related, here:

http://wiki.services.openoffice.org/wiki/Documentation/FAQ

The nature of most of the new questions I'm seeing suggest they will
ultimately end up in the "general FAQ" section of the main website,
here;

http://wiki.services.openoffice.org/wiki/Documentation/FAQ/General

if you look at those responses they are bullet lists when they are
enumerating a set of instructions for the user to follow.  Otherwise
they use complete sentences.  They are also conversational, speaking
in first person plural (we/our) perspective.  So let's try to adhere
to that style, if you can.  Otherwise, I'm happy to edit it later.


> One of the key starting points was to avoid that and I suggest you seek another author
you respect (obviously not me!) to help preserve the concise style the rest of us were using.
>

Let's see if anyone else thinks this is too verbose.  Remember, FAQ's
are not intended to be read as an article, one after another.
Typically they are things we we link to and point users to for
specific questions.

-Rob

> Thanks
>
> S.

Mime
View raw message