3:02 p.m.
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.
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. 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.
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]
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.
If the real focus currently is the End User, then the main documents
required are:
- 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?
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.
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.
--
Aaron Bowman, Fedora Docs Wannabe
gpg fingerprint: 2DD4 471F 12F4 FB93 986F 2B41 17DB 3139 CBF6 2385
11:06 p.m.
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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
6259
days inactive
6269
days old
1 comments
2 participants
participants (2)
-
Griff 5watt -
Karsten Wade