On Sun, 2007-04-29 at 14:48 -0700, Francis Earl wrote: > On Sun, 2007-04-29 at 17:05 -0400, Paul W. Frields wrote: > > The Documentation Project is basically here to oversee such efforts and > > make sure they maintain high standards of quality. We're happy to see > > motivated people stepping up to contribute content! > > I'm not sure how I take this, as I'm not sure exactly how you define > "high standards of quality". I believe they should be accurate, and I > believe they should be informative. I'm worried that this also includes > maintaining a professional feel to the documents. I believe that is the > wrong approach, depending on the target audience of each document. It > shouldn't feel like a text book to the user reading it, which is > somewhat the feel I got from the few documents I have read so far. I agree that we don't have to have the same tone of voice as e.g. Red Hat documentation. That's the text-book feel you are describing. However, that shouldn't affect quality. For example, when describing a set of steps to a user that includes stepping them through a GUI dialog, it is vital that the wording of the instructions matches what you see on screen 100%. Otherwise, the user loses confidence in the document. I see such mistakes very often, especially on the Wiki, where it is easy to whip out a document. Often a clever voice gets in the way of helping the user, which is why technical writing often squeezes out the cleverness in favor of clarity and accuracy. The same thing is true for grammar. When a document has common, obvious, or even subtle wording and grammatical mistakes, it undermines confidence in the document. Obviously, I'm a writer, so I have a prejudice here. Yet, would we ask our programmers to put out software that had similar mistakes? Well, we do, no software is perfect from the start, that's what the open source process provides us (a chance to continually correct.) So, a Wiki can accomplish all of these ends, but *only if* the team that maintains it can continually move the content toward clarity, technical accuracy, and grammatical correctness. It it those requirements that are the basis for this project. The Internet is full of how-to-do-stuff instructions that do not meet these "high quality of standards," and AFAIC, the Internet can keep them. They do help, sure, while they subtly undermine. This project is our chance to correct the undermining and make people's open source experience that much better. :-) - Karsten -- Karsten Wade, 108 Editor ^ Fedora Documentation Project Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject quaid.108.redhat.com | gpg key: AD0E0C41 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list