Official Fedora Handbook

Sat Oct 7 15:04:18 UTC 2006

Note: fedora-docs-list added to the Cc:; please join this list to
continue to the discussion.

On Sat, 2006-10-07 at 04:22 -0700, Eureka Trek wrote:
> Dear Ms Karsten Wade;

Just FYI, it is 'Mr.', but I'm not a person who is stuck on formalities,
we can drop the title all together and you can just call me
'Karsten'. :)

Please do not feel embarrassed at this common mistake; I'm sure others
on this list share the confusion, and I'm taking the opportunity to
straighten ya'll out.

> Back on October 2nd an individual using the handle
> "HudsonMan" posted a thread on FedoraForum entitled
> "It Is Time For The Official Fedora Handbook!".  Here
> is the link if you wish to read through the postings
> to the thread: 
> http://www.fedoraforum.org/forum/showthread.php?t=125807
> (the postings under the handle "eureka.trek" are mine)

Yes, the same person made a post on the subject on fedora-docs-list,
following the suggestion of Rahul.  As you requested, I just read
through the thread you posted.  No one has replied to HudsonMan/Markus
McLaughlin on the list mainly because we have been busy getting the
release notes ready for FC6.  I'm taking some time this morning to reply
to you and Markus to keep this great conversation going.

I am making my point-by-point reply to you and on the list because I
think the effort is best used in keeping the discussion there.  I
encourage you to join the list (and the project[1]).  We also are a very
passionate group who take pains to be open to new contributors who may
also be new to Linux.  Your ideas will be discussed with respect.  Our
project is one that new Linux and/or Fedora users can join and
contribute to very easily; we are a great entry point for becoming a
Fedora contributor. :)

> The purpose of my correspondence is to make some
> general enquiries concerning the issues presented in
> the above thread.  I hope that you can take the time
> to read through the above mentioned thread at
> FedoraForum and then address my questions below or to
> point me in the proper direction where the answers
> might be found.

We have discussed, settled, and even addressed many of the points
brought up in the fedoraforum.org thread.  I'll be happy to bring those
together into this discussion, which is what Rahul had in mind in
sending folks here.

> My questions are:
> 
> 1)  Has the Documentation Project taken up the task of
> writing an "Official Fedora Handbook"?

Yes, most definitely.  The format, title, and methods are somewhat
different than you and others propose.  We are using a mix of proven
and cutting-edge community documentation methods.

FYI, to settle something at the start, we have traditionally loathed the
word 'Official' in a title.  It is an overused word in technical
publishing and leads to confusion.

"The Fedora Handbook" IMHO carries a lot more weight anyway -- short, to
the point, impressive.

> 2) If the Documentation Project has taken up this task
> then where might people go to view it's progress
> and/or participate?

http://fedoraproject.org/wiki/Docs/Drafts

The short guides there are rather modular and can fit together into a
larger work, once completed.  You and all others are welcome and
encouraged to participate.  Right now, we are focusing on the new-user
friendly Desktop User Guide.  If you see anything in that draft that is
too high level for a new user, you are encouraged to get a Wiki
account[2] and fix it.

One thing we know from experience, which is reflected in a few posts in
the fedoraforum.org thread, is that it is *very* hard to write and
maintain an entire book from scratch.  For example, in the thread you
propose using screenshots for everything.  This is a very labor
intensive process, prone to error, and makes the resulting work much
harder to translate.  Writers who get books published through publishers
are either full-time writers or otherwise have the time to devote to
writing.  For a standard book, expect to commit >30 hours per week for 6
months.  Or more.  

Our experience with Fedora contributions is that it is not reasonable or
realistic to expect this level of commitment from one or several
individuals.  Even if someone can start at this level of commitment,
keeping it going for 6 months is a lot.

Once those 6 months have passed, the resulting book is now 3 to 6 months
out of date, referring to the *last* version of Fedora Core, and
therefore almost instantly obsolete.

This is why we are focused on i) online publishing, and ii) shorter
written works that can be grouped together into a manual/handbook.

Believe me when I say that all of these points have been thought out and
discussed multiple times over the years.  We could write up a Wiki page
to explain, but it is all in the archives for this list.  Just FYI if
you think I am too quick with my conclusions. :)

To get involved:

1. Join the list, start discussing.  That's easy:

http://www.redhat.com/mailman/listinfo/fedora-docs-list

2. Follow up on the new writers checklist:

http://fedoraproject.org/wiki/DocsProject/NewWriters

> 3)  If the Documentation Project has not taken up this
> task then what is the proper procedure as well as
> person(s) to contact for getting the necessary
> approvals so that someone/group desiring to take up
> this task could rightly place the word "Official" in
> the title of such a handbook?

Please understand that I am *not* being arrogant in saying that it is
unlikely that a random group of people who met on fedoraforum.org are
going to produce a full-length book in the manner described.

Well, to be balanced, I have to point out that random groups of people
have met and done many amazing things, such as producing Linux
distributions.  But all of this is usually best done by working with
existing materials and building from there.  It *can* be done from
scratch, but that is a much, much harder road to take.

This project has specifically been built from the ground-up with the
ability to:

1. Get new writers working on shorter works
2. Design such shorter works to fit together into a larger work

You can write and edit using the Wiki.  All content is published under
an open content license, the OPL[3], that allows us to share work with
other projects, or let other community members use the work as a basis
for their own documenting efforts.

Our real problem is a lack of volunteers, not a lack of ideas.  My goal
in replying to you directly and on this list is to continue trying to
attract and help with the efforts of such volunteers.

> Thank you for taking the time to read the thread and
> address these questions.  I look forward to your response.

Thanks for your enthusiasm.  I hope we are successful at turning the
energy into output.

[1] http://fedoraproject.org/wiki/DocsProject/NewWriters

[2] http://fedoraproject.org/wiki/Infrastructure/AccountSystem
I apologize for any difficulties in getting the necessary accounts in
place, etc.  We are trying to make this simpler, but there are real
reasons for the few barriers that are in place.  Do not hesitate to ask
for help in getting your account(s) setup, either on this list or via
IRC on irc.freenode.net, #fedora-docs.

[3] http://opencontent.org/openpub/

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061007/f35508e8/attachment.sig>