9:11 p.m.
Karsten Wade wrote:
Any questions or thoughts to start?
- Karsten
Thanks for the welcome!
My initial thoughts on the documentation is that it is perfect for
established users, i.e., those who have installed a Linux distro
previously. However, if I were to put my wife in front of two computers,
one with the docs on screen and one with Fedora on screen - she would
not really have a clue where to begin.
Looking at http://fedoraproject.org/wiki/DocsProject/DocIdeas I quite
like the look of the Fedora User Guide - this could be a crucial
document to help new users ease their way into Fedora & Linux in
general. I would see it as being written in a conversational style
rather than a straight 'here are the facts in a particular order'.
Depending on how in-depth we are looking it could also include some
task-based exercises to get users familiar with the software. What are
other people's thoughts?
If we are to succeed in promoting Fedora, then some of the barriers to
entry have to be removed - the Fedora User Guide would be a powerful
sledgehammer to pound down the walls of FUD.
Thanks,
Andy
9:28 p.m.
Andrew Hudson wrote:
Karsten Wade wrote:
> Any questions or thoughts to start?
>
> - Karsten
>
Thanks for the welcome!
My initial thoughts on the documentation is that it is perfect for
established users, i.e., those who have installed a Linux distro
previously. However, if I were to put my wife in front of two
computers, one with the docs on screen and one with Fedora on screen -
she would not really have a clue where to begin.
Looking at http://fedoraproject.org/wiki/DocsProject/DocIdeas I quite
like the look of the Fedora User Guide - this could be a crucial
document to help new users ease their way into Fedora & Linux in
general. I would see it as being written in a conversational style
rather than a straight 'here are the facts in a particular order'.
Depending on how in-depth we are looking it could also include some
task-based exercises to get users familiar with the software. What are
other people's thoughts?
If we are to succeed in promoting Fedora, then some of the barriers to
entry have to be removed - the Fedora User Guide would be a powerful
sledgehammer to pound down the walls of FUD.
Thanks,
Andy
Agreed 100%. I would say that is probably one of the most important
documents listed on that page. It should be no small undertaking. I
would say that the more in-depth you can make it without duplicating
other documents, the better. I know you are a talented writer, and I am
thrilled that you have taken interest in this task. Would you care to
put together a quick outline of your thoughts for this document?
You're going to need write access on the wiki quickly enough. If you
haven't already, create a wiki account, and then let us know what your
wiki name is so we can grant you the necessary privileges.
--
Patrick "The N-Man" Barnes
nman64(a)n-man.com
www.n-man.com
--
11:08 p.m.
Andrew Hudson wrote:
Patrick Barnes wrote:
>
> You're going to need write access on the wiki quickly enough. If you
> haven't already, create a wiki account, and then let us know what your
> wiki name is so we can grant you the necessary privileges.
>
Wiki name is AndrewHudson - grant away :)
Andrew
I have added you to the EditGroup of the wiki. This will allow you to
make changes to the existing materials on the wiki. We are currently
working on a new wiki infrastructure for drafting documents. As this
progresses, you will be granted additional permissions as needed to use
the new system.
--
Patrick "The N-Man" Barnes
nman64(a)n-man.com
www.n-man.com
--
12:20 a.m.
Andrew Hudson wrote:
Karsten Wade wrote:
> Any questions or thoughts to start?
>
> - Karsten
>
Thanks for the welcome!
My initial thoughts on the documentation is that it is perfect for
established users, i.e., those who have installed a Linux distro
previously. However, if I were to put my wife in front of two
computers, one with the docs on screen and one with Fedora on screen -
she would not really have a clue where to begin.
Looking at http://fedoraproject.org/wiki/DocsProject/DocIdeas I quite
like the look of the Fedora User Guide - this could be a crucial
document to help new users ease their way into Fedora & Linux in
general. I would see it as being written in a conversational style
rather than a straight 'here are the facts in a particular order
I am not fond of the "user guide" name. It isnt specific enough for my
taste. If we have a system administrator guide tommorow, it would like
those people arent users of Fedora. If you are writing about the
desktop, call it a desktop guide. It is what it is
regards
Rahul
12:54 a.m.
Rahul Sundaram wrote:
I am not fond of the "user guide" name. It isnt specific enough for my
taste. If we have a system administrator guide tommorow, it would like
those people arent users of Fedora. If you are writing about the
desktop, call it a desktop guide. It is what it is
Rahul,
I agree with you - I was just referring to the name that it has
currently been given in the DocIdeas wiki page.
I'd much prefer that it was something slightly appealing about it,
perhaps 'Fedora Desktop 101', or 'Getting Productive with Fedora'. At
least these two titles are perhaps more informative and helpful than
just Desktop Guide. What do other people think?
I'm going to have a think about an outline for such a document today and
try to post later on when I have chance. My initial thoughts are to have
a self-contained document covering all aspects of Desktop Fedora,
limited initally to packages included in Core.
And on the subject of informative and helpful - do we default to US
English for docs?
Thanks,
Andrew
7:56 a.m.
On Wed, 2005-08-24 at 10:50 +0530, Rahul Sundaram wrote:
Andrew Hudson wrote:
> Karsten Wade wrote:
> > Any questions or thoughts to start?
> >
> > - Karsten
> >
>
> Thanks for the welcome!
>
> My initial thoughts on the documentation is that it is perfect for
> established users, i.e., those who have installed a Linux distro
> previously. However, if I were to put my wife in front of two
> computers, one with the docs on screen and one with Fedora on screen -
> she would not really have a clue where to begin.
>
> Looking at http://fedoraproject.org/wiki/DocsProject/DocIdeas I quite
> like the look of the Fedora User Guide - this could be a crucial
> document to help new users ease their way into Fedora & Linux in
> general. I would see it as being written in a conversational style
> rather than a straight 'here are the facts in a particular order
I am not fond of the "user guide" name. It isnt specific enough for my
taste. If we have a system administrator guide tommorow, it would like
those people arent users of Fedora. If you are writing about the
desktop, call it a desktop guide. It is what it is
Yet this nomenclature is commonly accepted throughout the tech industry,
and therefore going against it may be confusing when people are trying
to assess what kind of skills they have learned. I think a good way of
looking at the problem is by drawing the dividing line at the point
where you require the root password. The User Guide should be developed
parallel with the Administrator Guide. People can easily get their
hands on both, and there is absolutely no reason why they couldn't
cross-reference each other.
We need to think about this documentation, as Tommy Reynolds so
helpfully pointed out in some other thread, as more than just serving
hobbyist home users. Consultants and professionals may also find value
in these documents and they need to serve those needs as well.
Any task that requires the root password should be in the Administrator
Guide. This simplifies life for sysadmins who want to distribute the
User Guide in an office to the customers (users) they serve. It is not
helpful to those sysadmins for their users to start reading about
administrative tasks that are out of their purview. Any reader who
wants to learn can be expected to pull down as many guides as she wants
to learn how to run her system fully.
If we take the "Desktop Guide" idea to its logical conclusion, the
Installation and any Security Guides should be included in it as well.
That makes for a large, unwieldy, and awkward document to manage. Even
though Guides are larger, they should be split along logical lines, and
I think the model above provides an easy answer to doing that.
Does this mean that home users will have to refer to more than one
guide? Yes, but if the Web site and/or pointer materials have simple
instructions for which guide to consult, that is not a problem. For
instance:
"If you want to learn how to install a Fedora system, consult the
Installation Guide <URL>."
"If you want to learn how to perform common tasks on your Fedora system
or change your personal user preferences, consult the User Guide <URL>."
"If you want to learn how to change global system settings or administer
network services on your Fedora system, consult the Administration Guide
<URL>."
"If you want to learn how to further secure your Fedora system, consult
the Security Guide <URL>."
Although the line of "root password required" is (IMHO) a great place to
divide the guides, there may be a call for a *short, sweet* "Getting
Started Guide" that discusses only the MOST basic tasks and talks about
the differences between the roles of user and administrator. This would
help the brand-new user know when they need to look at the User Guide,
and when to look at the Administration Guide. This type of setup worked
very well in the original Red Hat guides, and there is no reason we
should not follow a model that works well.
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
8:02 a.m.
Hi
Although the line of "root password required" is (IMHO) a great place to
divide the guides, there may be a call for a *short, sweet* "Getting
Started Guide" that discusses only the MOST basic tasks and talks about
the differences between the roles of user and administrator.
It has been pointed out before but any tool that requires a password for
a desktop functionality is broken. We should divide by functionality.
Not by whether it requires a root password or not
regards
Rahul
8:41 a.m.
On Wed, 2005-08-24 at 18:32 +0530, Rahul Sundaram wrote:
>Although the line of "root password required" is (IMHO)
a great place to
>divide the guides, there may be a call for a *short, sweet* "Getting
>Started Guide" that discusses only the MOST basic tasks and talks about
>the differences between the roles of user and administrator.
>
It has been pointed out before but any tool that requires a password for
a desktop functionality is broken. We should divide by functionality.
Not by whether it requires a root password or not
Can you give some examples? I am trying to figure out which tools this
would apply to. I don't recall getting password prompted for anything
which *wasn't* a global system setting change that would affect other
users on a managed system.
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
8:51 a.m.
Paul W. Frields wrote:
On Wed, 2005-08-24 at 18:32 +0530, Rahul Sundaram wrote:
>>Although the line of "root password required" is (IMHO) a great place
to
>>divide the guides, there may be a call for a *short, sweet* "Getting
>>Started Guide" that discusses only the MOST basic tasks and talks about
>>the differences between the roles of user and administrator.
>>
>>
>>
>It has been pointed out before but any tool that requires a password for
>a desktop functionality is broken. We should divide by functionality.
>Not by whether it requires a root password or not
>
>
Can you give some examples? I am trying to figure out which tools this
would apply to. I don't recall getting password prompted for anything
which *wasn't* a global system setting change that would affect other
users on a managed system.
I was talking about a general idea, not specific bugs
http://mail.gnome.org/archives/desktop-devel-list/2004-June/msg00161.html
regards
Rahul
9:46 a.m.
On Wed, 2005-08-24 at 19:21 +0530, Rahul Sundaram wrote:
Paul W. Frields wrote:
>On Wed, 2005-08-24 at 18:32 +0530, Rahul Sundaram wrote:
>>>Although the line of "root password required" is (IMHO) a great
place to
>>>divide the guides, there may be a call for a *short, sweet* "Getting
>>>Started Guide" that discusses only the MOST basic tasks and talks about
>>>the differences between the roles of user and administrator.
>>>
>>It has been pointed out before but any tool that requires a password for
>>a desktop functionality is broken. We should divide by functionality.
>>Not by whether it requires a root password or not
>
>Can you give some examples? I am trying to figure out which tools this
>would apply to. I don't recall getting password prompted for anything
>which *wasn't* a global system setting change that would affect other
>users on a managed system.
>
I was talking about a general idea, not specific bugs
http://mail.gnome.org/archives/desktop-devel-list/2004-June/msg00161.html
Havoc is talking about usability improvements (and 12 months later, in
FC4, we can see the effects of work on that front) and how to organize
preference tools. When he says a root password does not drive
development of the user experience, he's right. But documentation
discusses the system *as it exists*, not *how you wish it was*. Moving
a piece of documentation from one Guide to another doesn't impact on the
usability of the system, it's just a link (whether a hyperlink or a
conceptual link) from one page to another.
Nevertheless, here's the upshot, that DocBook XML lets us easily grab
<section> modules and drop them from one doc into another. As D-BUS and
a few other enabling technologies change the interaction that a "normal"
user has with the system, sections can migrate from an Admin Guide to a
User Guide easily.
If running a specific tool requires the administrator password, a
managed user (again "managed user" means "user in the workplace who
doesn't necessarily have root") is not going to have access to it.
Telling that person how to do something she is not allowed to do causes
more aggregate frustration than telling readers "refer to the Admin
Guide for information on how to do XYZ."
Again, cross-referencing solves the problem for home users and other
people who own their system. If the developers make a mistake in
deciding to keep a user from making a perfectly reasonable system
setting change, it has a far-reaching impact. And if the control tools
for changes a user *can* make are organized wrong, the system is harder
to use. That's Havoc's point. But using the root password as a
dividing line for where to document a tool is still reasonable, since it
follows the generally accepted methods of technical documentation.
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
5:31 p.m.
On Wed, 2005-08-24 at 10:46 -0400, Paul W. Frields wrote:
Nevertheless, here's the upshot, that DocBook XML lets us easily
grab
<section> modules and drop them from one doc into another. As D-BUS and
a few other enabling technologies change the interaction that a "normal"
user has with the system, sections can migrate from an Admin Guide to a
User Guide easily.
Importantly, because <xref>s are done against ID attributes, the link
follows the <section> moving.
However, this means we *must* have unique IDs at least within a
particular series of books, if not across the entire doc-set. We
probably won't have many duplicates, but it happens especially when the
same writer has been making up IDs for days on end. :)
If running a specific tool requires the administrator password, a
managed user (again "managed user" means "user in the workplace who
doesn't necessarily have root") is not going to have access to it.
Telling that person how to do something she is not allowed to do causes
more aggregate frustration than telling readers "refer to the Admin
Guide for information on how to do XYZ."
Again, cross-referencing solves the problem for home users and other
people who own their system. If the developers make a mistake in
deciding to keep a user from making a perfectly reasonable system
setting change, it has a far-reaching impact. And if the control tools
for changes a user *can* make are organized wrong, the system is harder
to use. That's Havoc's point. But using the root password as a
dividing line for where to document a tool is still reasonable, since it
follows the generally accepted methods of technical documentation.
+1
This is a good way to split. If root is required, it's in the Admin
Guide. If not, it's in the Desktop User Guide.
BTW, that's my solution for the different names. :) DUG is a nice TLA.
~ Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
6:52 p.m.
On Wed, 2005-08-24 at 15:31 -0700, Karsten Wade wrote:
BTW, that's my solution for the different names. :) DUG is a
nice TLA.
Much better than FUG. Being fugly was always bad, at least when I was
in school.
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
6:52 p.m.
On Wed, 2005-08-24 at 03:11 +0100, Andrew Hudson wrote:
Looking at http://fedoraproject.org/wiki/DocsProject/DocIdeas I quite
like the look of the Fedora User Guide - this could be a crucial
document to help new users ease their way into Fedora & Linux in
general. I would see it as being written in a conversational style
rather than a straight 'here are the facts in a particular order'.
You're definitely on the right track.
Personally, I'm going to be very picky about how a conversational style
is done. Comes across like Bill Bryson, that I can take. IMO, this is
a style that is harder to get right than wrong. Harder than a neutral
style. Harder to collaborate on.
It's an interesting topic to discuss. Product documentation usually
takes a neutral tone. I like how this neutral style gets out of the
user's way and focuses on the software.
Books need to appeal to readers to attract them, i.e., they don't have
the advantage of being bundled with the software. They are written to
target a group of readers.
The Fedora Desktop User Guide (my suggestion for a working title) would
be the most likely location to take a conversational style. Perhaps a
test bed?
- Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
6830
days inactive
6830
days old
14 comments
5 participants
participants (5)
-
Andy Hudson -
Karsten Wade -
Patrick W. Barnes -
Paul W. Frields -
Rahul Sundaram