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/