Here is my challenge, let's see if we can do it!

Sat Oct 7 15:55:16 UTC 2006

Sorry for taking a few days to respond.  We've been busy this week
getting ready for the FC6 release.  I responded separately to Eureka
Trek.  Pardon my brief(er) response to this, I want to keep the
discussion going and also get some other work done today. :D

On Thu, 2006-10-05 at 16:11 -0400, Markus McLaughlin wrote:
> UBUNTU!  This is all I hear and read about these days, every other  
> Linux OS is suffering because of it!  And what is worse, Windows  
> Vista is trying to lure people away from Linux altogether.  This has  
> to slow down or stop completely.  

I won't agree with you, but that's OK.  People are welcome to use Ubuntu
or whatever, if that is what they prefer.  As far as I am concerned,
Ubuntu are "friendlies" in the war on bad software and closed systems.
We have different ways of doing things.  With 6+ billion people on
Earth, we can afford more than one successful Linux distribution. :)

By working with a friendly license and open content, we all gain in the
same way that pushing changes into the upstream kernel benefits all
Linux distributions.

> Ubuntu just came out with its first  
> Official Handbook, this is not good for us, Fedora Fans/Programmers.   

IIRC, this was published by a regular publisher.  You mean this book,
right?

http://www.amazon.com/Official-Ubuntu-Book-Benjamin-Mako/dp/0132435942/ref=pd_sim_b_1/102-8757914-8963356?ie=UTF8

I happen to know a little bit about how that book was put together.  We
are prepared to take on that level of effort, but it is going to require
volunteer contributors and some level of risk for "real writers" who
want to get involved.  Make no mistakes here -- for a book to be
published, it is going to take planning, work, and editing.  It cannot
be on the level of the usual writing that I see in most places.

> SO!  I propose we band together and crank out 

This is an honest question not meant to insult.  Do you have experience
writing or publishing books?  If you want something that is worth the
effort put into it, you cannot simply crank it out.

Community documentation is a wonderful idea that works well in practice.
For it to have high quality and be useful (accurate, readable,
translatable, etc.), it takes *much* more work than you imply.

I do not think it is impossible; in fact, with the proper incentive[1],
I think it is *very* possible.  But we are not going to get there by
glossing over the challenges.  Those challenges will rise up and bite us
at every step if we do not do something to mitigate them at the start
and as we proceed.

> a $20 Handbook with FC  
> 7 DVD, Red Hat Enterprise Linux 5 Client Demo CD with PDF Intro to RH  
> Enterprise Linux 5 Client/Server, AND a FREE PDF for the next Fedora  
> Core, version 7.

I don't understand what having Enterprise Linux in there does, except
create confusion.  FC7 is going to be six+ months beyond what is in RHEL
5.

>   To test out what we will write, we should put  
> together a FREE PDF "Handbook" for Fedora Core 6.  If that proves  
> successful, we should move forward to Fedora Core 7.  FC7 must have  
> the PDF and an order form web site link for the book itself on the  
> DVD release.  Half of the proceeds must go to the Red Cross (http:// 
> www.redcross.org) aiding Hurricane Katrina Relief with the other half  
> to pay for blank media for copying the ISO images from the download  
> mirrors.

I don't disagree with the idea of funneling some proceeds into worthy
causes.  Howeve, relief for damage from hurricane Katrina is very
US-centric for such a global distribution.  Realize that our user base
is *huge* in many other countries where the average person's living
situation is like being born into and living your whole life in a
Katrina-ravaged zone.

I'd recommend that we separate the idea of contributing proceeds into
some kind of survey or vote that draws opinions from across Fedora.  I'm
sure there are other opinions here.

> The Official Fedora Handbook - Fedora Core 6 - October 2006

Please see my other message about the word "Official" in titles.  Let's
just avoid it. :)

> (PDF version generated November 2006)

Do you really think we can write a book in the next 30 days?

I am not trying to pop your balloon.  But there is a huge gap between
enthusiasm and getting the work done.  I've seen a lot of people who
think good or sufficient documentation can be "cranked out" in a few
days.

Figure 8 hours per page in research, writing, fact checking, technical
and grammar editing, and publishing work.  For one person, this is
equivalent to about 800 hours for a 100 page book.  With an average of
about 2000 hours of worktime in a year (40 hours per week), that is
almost six months to complete.

When working on a book with other people, there is more overhead.
Coordination, work to normalize the voice/writing style so that it is
not jarring to the reader when they switch between sections written by
different people, etc.  Figure on adding about 2 hours per page for this
management coordination.

Naturally, having more people on the project helps divide that work, but
at an increased cost of coordination.  Taking the 10 hours per page
estimate for five dedicated writer/editors:

10 hours x 100 pages = 1000 hours
1000 hours / 5 = 200 hours per person
200 hours = 5 weeks of fulltime (40 hours/week) work

Do you have five people who can dedicate that much time between now and
November?  I'm sad to say that this project does not have that level of
resources.  And the smaller you divide the 1000 hours by people, the
higher the overhead rate.  10 people might require 11 hours per page,
etc.

Then you have the time to coordinate with people outside of the writing
project.  You mention quotes from developers, etc.  There is also the
need for a technical and usability edit from outside of the core group.
All of this has to be coordinated in real time, meaning that an 8 hour
work day does not necessarily equal 8 hours of schedule completed.  On
average, you can figure about 6 hours of real writing work for a
writer's 8 hour day, with that 2 hours spent on email coordination, etc.
Some of this is figured into the overhead I specified, but to be honest,
you can't quantify all of it.  We'll need an additional buffer in the
estimate to cover that.

Again, I'm not trying to say your idea is overall impossible.  I'm
pointing out where reality intercedes with well laid plans. :)

> 1. Introduction to Fedora Core 6
> 2. Installation - Everything explained with color screenshots to  
> illustrate the details.
> 3. Configuration - How to set up the Applications / Servers / Base /  
> Language Support
> 4. Exploration - Getting to know the Desktop GUI for both GNOME and KDE.
> 5. Projects - Different tasks that can be accomplished with the  
> Applications /  Add-Ons.
> 6. Advanced - Learning the Command Line and System Mechanics
> 7. Future Directions - What is being worked on for Fedora Core 7
> 8. Introduction to Red Hat Enterprise Linux 5 Client/Server - Moving  
> to the next level
> 9. Conclusion
> 
> I would like to be in charge of the Introduction and Conclusion with  
> cool quotes from different sources.  This Handbook should be like  
> those "Dummies" books with little insights from the programmers on  
> why they put in this particular code.  There should be "side lines"  
> where a
> lead programmer or Fedora enthusiast talks about WHY they use Fedora  
> Core instead of
> some other competing Linux OS.  It would be wise to have HIGHLIGHTED  
> words in bold,
> code in Typewriter Font, and references in Italic or in the color  
> blue.   Review the Ubuntu Handbook and the previous Fedora Core for  
> Dummies books for references to everything
> I have mentioned. 

Have you had the opportunity to look into what the Fedora Documentation
Project has in terms of standards and processes?

I suggest you start here:

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

And look here:

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

and here:

http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms

>  I can be reached at markmc34 at verizon.net

Please join this mailing list if you haven't already so we can continue
these discussions and begin the hard work.

- Karsten

[1] My thoughts on why it is worth it to individuals to
contribute/volunteer to open content/community documentation efforts:

http://iquaid.livejournal.com/13095.html

-- 
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/ae749e9d/attachment.sig>