[Fedora Project Wiki] Update of "Docs/Drafts/DesktopUserGuide/Desktops" by JohnBabich

[John Babich]

On 5/20/07, Karsten Wade <kwade at redhat.com> wrote:
> On Sat, 2007-05-19 at 20:12 +0300, John Babich wrote:
> > I guess I'll have to do my very rough drafts offline from now on :-)
>
> While I'm sure you have your tongue in your cheek with this comment
> (hence, the smiley), I want to take the chance to point out why
> community documentation *can* be better than solo-doc writing.  It is
> because of open collaborative teamwork.
>
The above remark was definitely made tongue-in-cheek with a hint of
frustration. The frustrating part is trying to figure out the best way to
change the format to fit the greatly expanded scope of coverage. Also
note the emphasis on the "very" in the "rough draft".

> The open collaborative process gives us a chance to fix problems early
> and often.  If writers keep their prose secretive until they feel it is
> perfect, several things may happen:
>
> * If it is not perfect, there is less time and inclination to fix it
> * The longer you hold in to a piece of writing, the harder it is to let
> go of it when changes must be made
> * Others are given less of a chance to learn from common mistakes and
> guidelines.
> * Ongoing editing (a strength of a content control such as Wiki or CVS)
> is harder to do when content arrives in huge blobs.
>
> (Note that all this can be said about code.)
>
This is the strength of open source - release early and often. I agree with
you that it also applies to writing documentation.

> The last one is where I often fall short.  I follow the traditional
> route of saving my edit for the end, and then I have a HUGE amount of
> work ahead of me -- all of the work needs to be done in one pass, and
> any lessons I want to pass (similar to Paul's) are less visible when
> passed during a massive edit campaign.
>
> For example, a few weeks ago I actually did some editing of FWN before
> the writer's deadline.  The tips I passed along in that edit were then
> followed for newly written content, which reduced my final edit
> workload.
>
I have been suffering from "analysis paralysis", also known as "writer's
block". That's why I decided to go with a "brain dump" to get the creative
juices flowing.

At the same time, it was a bit upsetting to have this doc critiqued rather
heavily while clearly in the early stages (at least in my mind). It's
like trying
to write a song and somebody comes along and says, "Hey, dude, your
instrument's out of tune".

Keeping On Keeping On,

John Babich
Volunteer, Fedora Docs Project