Wiki musings

[Greg DeKoenigsberg]

My biggest question here:

Do we distinguish between "documentation for using Fedora" and 
"documentation for helping to produce Fedora"?

A lot of the stuff that is "documented" on the wiki is process for 
contributors.  "How do I get a package into Extras?"  "How do I get an 
account in the accounts system?"  And so forth.  These seem like living 
documents to me.

Do you have some good examples of wiki documents that you'd like to 
formalize?

--g

_____________________  ____________________________________________
  Greg DeKoenigsberg ] [ the future masters of technology will have
 Community Relations ] [ to be lighthearted and intelligent.  the
             Red Hat ] [ machine easily masters the grim and the 
                     ] [ dumb.  --mcluhan

On Tue, 23 Aug 2005, Karsten Wade wrote:

> We had a lively discussion about Wiki at the FDSCo meeting this week.  
> 
> Here is my summary of the current argument and ideas:
> 
> Fact:  The community has bypassed FDP technologies in favor of the Wiki
> 
> Fact:  To still be the project that handles Fedora documentation, we
> need to address this activity.  These docs need to be brought into the
> fold, and a process created to formalize them.
> 
> Why the last fact?
> 
> Our goal is to create high quality documentation for Fedora.  Tools are
> not specified in that goal.  Just the quality.  Printable, packageable,
> viewable with XML viewers, useful offline as well as on.
> 
> To ensure quality, we need:
> 
> * Actual technical and grammatical editing
> * Some control over some kinds of content, to protect from accidental or
> malicious tampering
> * Multiple output formats for our finished documentation
> 
> To get those, we need to move our process to include the Wiki.
> Otherwise, there is a growing amount of documentation that is within the
> project because it is hosted on fedoraproject.org, but is not QA'd or
> available for printing, etc.
> 
> Here are some ideas for how to accomplish this:
> 
> * Create a structure in the Wiki that will let us host a Docs/Drafts/Foo
> and a Docs/Foo, to help differentiate draft content
> 
> * Draft documents must have the word Draft in their title, perhaps even
> their Wiki title?  The name could be changed (using a rename or a
> #redirect) to the final doc, when finalized.
> 
> * Editors need to subscribe to /Docs/Drafts/* and help writers by
> watching content changes.  Via RSS feed, if they prefer.
> 
> * wiki/Docs/Drafts/ needs to be closed to all but those in the
> DocWriters groups.  This membership should be easy to obtain.
> 
> * Wiki/Docs/ needs to be for DocEditors only
> 
> * We can add people to those groups quickly and easily, and we encourage
> cross-work.  If you see something that needs fixing within those trees,
> fix it, knowing others are watching you to help fix your mistakes.
> 
> * To be promoted from wiki/Docs/Drafts to wiki/Docs/ requires an editor
> approve the document as ready to publish.  Once it's moved, the writer
> can continue to work on it.  Anyone else who wants to work on it need
> only be in the DocWriter group, which is the same as described in
> NewWriters.  Developers need to have self-intro'd on some mailing
> list. :)
> 
> * New documents can be written and abandoned in Docs/Drafts/.  We'll
> have quarterly clean-ups and purge cruft.  This is a safe scratch space,
> well marked with "Tygers Be Here, Users Run Away!!"
> 
> * Formal documents should be available in PDF, tarball, and RPM format.
> To accomplish this, part of promoting every document to Docs/ is to
> create a CVS module for it and get the Wiki to pull from CVS instead of
> its own flat-files.
> 
> This last part is the one that requires some new infrastructure.  I am
> working on this with Seth and Elliot.  The idea is to edit the XML
> directly through the Wiki, with the XML stored in CVS and thus part of
> the whole build system.
> 
> Bottom line is, your choice of what tool to edit your content should not
> stop us from fully utilizing your content.
> 
> Opening up our documentation this way will attract developers who won't
> fool with XML in CVS.  We just give them DocWriter access, and away they
> go.
> 
> Thoughts?
> 
> - 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/
>