Docs Project Structure?

Thu Mar 1 05:06:48 UTC 2007

On Mon, 2007-02-19 at 16:02 -0500, Griff 5watt wrote:
> I just recently got involved in the Docs Project and while getting my
> head into it all, I had a few thoughts.  Please let me know if I am
> missing something.

Sure thing; didn't mean to let this email stay unreplied-to for so long,
but it is worth pausing and considering your points.

> I read through the information in the wiki and did not see anywhere an
> explicit mission statement about the Docs Project.  Specifically what
> I was looking for was information as to who the documentation was
> geared for.  

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

Yep, it's definitely missing from that page.

Ironic.  I know it's been discussed before.  One thing that we think of
as self-evident, and which is obviously not, is that our mission is
derived from the overall Fedora Project mission.

Yet ... yet, this doesn't include some of the mission that we have
accepted over the years, such as the care and feeding of the newbie
user.

> The 'Documentation' link on the front page of the Fedora Project wiki
> brings up an unclear picture of the documentation as well.  The
> designation between the target audiences is not clearly defined,
> flowing from [End User] Published Documents and Draft Documents right
> into New Contributors and Developers. 

This is a natural consequence, originally, of the dichotomy we have.
The formal project *specifically and explicitly* does not have the care
and feeding of the newbie at the center.

So, starting from that, we would want to focus only on power and expert
users.

However, in Linux documentation, that space is fairly well occupied.
And more people came to this project interested in helping out newer
users.  We have yet to reconcile that dichotomy into a new, encompassing
mission.

> From what I have seen, there are three major categories that
> documentation falls under.  1) The End User [defined below]; 2) The
> Developer; 3) Other contributors.
> 
> For me, the End User is the person looking to install and use Fedora
> Linux.  This person may be a home user doing email and watching videos
> on the web; or the office worker doing email, documents and
> spreadsheets; or the administrator supporting the office worker; or
> the web developer who is doing their work on Linux.  [+1] 

Agreed.  There is also a cross over, in that developers and contributors
are also end users.

> Those who are involved in the development of Fedora Linux or
> contribute in other ways are separate from the End User.  There was
> some talk at FUDCon about dividing the front page into three
> sections... End User, Contributor, Developer.  Documentation should
> follow this division as well. 

It was more like, "Get, Learn, Join."

Then from within each of those would be striations by experience.  For
example:

Get => 
      Fedora Linux (Anyone, newbies)
      Specialized ISOs (Anyone)
      Source code (power users)
      CVS access (developers)

Learn =>
      How to general stuff (new users)
      How to do system admin stuff (power users)
      How to hack the distro (developers)

Join =>
      Promote and spread the word (ambassadors)
      Essential and fun work (trans, docs, infrastructure, websites)
      Make the distro (packagers)
      Code the distro (developers)

> If the real focus currently is the End User, then the main documents
> required are:

What I think has happened is this:

* Sub-projects provide how-to-do-stuff-here for their own projects
(covers packagers, developers, trans, infrastructure, etc.)
* The power user/system administration level is still quite well covered
from the community
* This leaves the end user (as you call them), which we still need to
define to some degree

Maybe a good working definition of End User is, "New to Linux but not
new to computing."  For example, we don't want to be telling people how
to use a mouse or what a GUI windowing system is.  We are presuming some
experience.

One way we have tackled this was to have *each document* define its own
audience, rather than picking one audience for the whole project.  If
you look at the top of each/most of these draft documents, you'll see
the audience specified:

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

> - The Installation Guide (How do I get Fedora Linux onto my machine?)
> [available on fedora.redhat.com/docs/]
> - The Desktop Users Guide (Now, what can I do with this default
> install?) [available from the fedoraproject.org wiki]
> - System Maintenance (How can I keep it running well?) [not
> available?] 
> - Software Installation (How can I get more applications that will
> hose my system?) [available? from fedora.redhat.com/docs/ 'Managing
> Software with YUM']
> - and Support (What do I do to solve my problem?) [not available?]
> [+2] 
> 
> Are there documents for Maintenance and Support? 

Some of the topics are covered in

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

Calling them out as separate functions like that (maintenance,
support) ... is that from the viewpoint of your identified audience?

> Anyway, I am going to get back to reading what is currently out there
> and try to be a constructive member of the group.
> 
> ------------------------
> 1) I expect that our sponsor would prefer that the Office Worker,
> Developer and the Administrator end-users would be using RHEL rather
> than Fedora Linux, otherwise they would be eager for Fedora to provide
> a server spin, thereby negating the need for the Fedora Project to
> handle this documentation.  However, if Fedora is truly to provide the
> base for RHEL, then this would include documentation for these
> users.  This requires more direction from the appropriate
> people.  This leaves us with the Home User. 

I don't think we really need to consider Red Hat's commercial/business
desires in this area.  We are here to respond to the Fedora community.
Otherwise we wouldn't have any focus on the new-to-Linux, with the
historic attitude of Fedora-for-the-Linux-hobbyist.

As for documentation provided for the various other audiences, the RHEL
content services team has that pretty well sewed up:

http://www.redhat.com/docs/manuals/enterprise/RHEL-5-manual/

Rumor has it that Fedora is supposed to receive that content as a
contribution.  If we accept the contribution, we are either upstream,
downstream, forked, or cross-stream of that content.  Either way, we'll
see what we do when we have actual source in hand.

> 2) In my view this document would start out with a brief list of those
> tools that would be helpful in trouble shooting problems, and how to
> use them.  Then a list of external sites would be provided that would
> allow the user to research their individual issue on their own, i.e.
> fedoraforum.org, linuxforums.org, and linuxquestions.org.

I like this idea.  If there is not something that covers this in
Docs/Drafts, you might want to start outlining there and see where it
goes.

There are some other pages that might be worth including:

http://fedoraproject.org/wiki/Bugzilla
http://fedoraproject.org/wiki/BugsAndFeatureRequests

cheers - 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/20070228/12aacb2b/attachment.sig>