[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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



On 5/20/07, Karsten Wade <kwade 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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]