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.