Fedora User Guide

Karsten Wade kwade at redhat.com
Wed Aug 24 22:31:05 UTC 2005


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/
-------------- 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/20050824/0e2b8054/attachment.sig>


More information about the fedora-docs-list mailing list