Wiki musings

[Karsten Wade]

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/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050823/9919b842/attachment.sig>