what makes you write community documentation?

[Karsten Wade]

Attached is the original I cut out from the email, a revised version,
and a standard diff between the two.  Hopefully that makes it easier to
see each individual edit.  I made all edits to bring the document in
line with standard guide lines; this 100% edit is the level of edit I
would only expect to do a few times for a writer before they picked up
the changes enough to send in nearly perfect copy.

Some quick observations:

* This would be easy to do in the Wiki, right into the Admin Guide

* Then you could get some nicer markup to e.g. differentiate commands
and file paths, etc.

* The WikiEditing page has a short and useful section on doing technical
markup for consistency:
http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms

* This is also useful for Docs-specific items:
http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki

* I trimmed all the screenshots; the text described them fine, and has
the advantage of being easily translatable.  Read it, you can see that
the screenshots didn't add anything, especially where the text is
accurate with what is seen on the screen.

* When there is the need to describe command line output, just paste
that directly in; it is much easier to fix, etc.  It has the advantage
of letting someone copy/paste commands directly from the document.

* When describing anything the user sees directly, such as a command
input/output or a GUI window, it is very important that what you write
is 100% what the user sees.  If the button is called "Stop" and not
"stop", capitalize it in the writing to make it match the UI.  Even if
the UI is inconsistent, be consistent with it.  This grows confidence in
the reader. :)

Since you can write this stuff fairly quickly, it is pretty good raw
content as-is, and I'm sure you have the capacity to improve your
writing :), let's figure out what you need to do to get a Wiki account.

- Karsten
-- 
        Karsten Wade              ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
    quaid.fedorapeople.org        |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20070815/1657eb46/attachment.bin