Maintenance/Brevity vs. Explicit Instructions

[Paul W. Frields]

On Thu, Jan 01, 2009 at 12:18:19PM -0500, Matthew Daniels wrote:
> The other day I noticed someone mention in #fedora-docs how much of a  
> maintenance nightmare it is to have the same user instructions  
> replicated over multiple places.  In the process of editing the UG, I've 
> been thinking; is there a good reason that this happens, or is it just 
> because of the way docs get tangled up over time?
>
> For example, the User Guide has multiple places where the user is  
> instructed to install new software.  I understand that there is some  
> value in repeating the instructions every time this happens, but is it  
> worth the nightmare is causes with maintenance and uniformity?  Would it 
> not be better to simply keep the canon set of instructions in one place 
> (like User Guide - Managing Software) and consistently refer the user to 
> these instructions?
>
> Just curious for everyone's opinion on this.  Kinda wanted to bounce it 
> around before I change everything.

I think I left a spurious comment like that in the channel, but I was
referring specifically to the many repetitive pages I found concerning
our process, workflow, instructions, and so forth.  In the course of
trying to make sure we don't leak knowledge, I'm sure we've
inadvertently created many repetitive pages on the wiki.  Those pages
might then confuse new folks trying to figure out which directions are
canonical.

If the instructions in question are fairly short, the value in cross
reference is low.  Making the user break out of the continuity of a
document to go to another page should only be done if the instructions
are quite substantial and otherwise not really on-topic.  An
instruction like the one-line explanation "Install the XYZ package
using the following command:  su -c 'yum install XYZ'" would not be
worth cross-referencing.  A detour into creating a Fedora account, on
the other hand, contains numerous steps and is much better left to a
cross-reference, I'd think.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20090101/97ceab3c/attachment.sig>