Wiki musings

[Patrick Barnes]

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
>  
>
Once we have the ACLs in place, they will be a big part of this.  We can
refine more as needed.

>* Multiple output formats for our finished documentation
>  
>
That's the beauty of DocBook.  In addition to the formats that can be
rendered directly, we can daisy-chain additional tools to add support
for other formats.  Obviously, the wiki won't provide this, though.  If
we can get the wiki using other sources as backends, we might be able to
get other formats out of the draft documents, too.  When it comes time
to move documents from the wiki into another repository, there will be a
little bit of work to be done, but we can hopefully automate this
entirely in the long run.

>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
>
>  
>
This is very true.  It will take a little work/time to figure out
exactly what the best structure will be.  I know you have already
started, and over the next few days, I'll probably flush out a few
ideas, too.

>* 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.
>
>  
>
If we use the /Drafts/Name structure, the /Drafts part will provide that
much.  We can create a DraftsCategory, too.  This could help out in a
few other ways too...

>* 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.
>
>  
>
Easy to manage once the ACLs are up.

>* Wiki/Docs/ needs to be for DocEditors only
>  
>
Also covered by the ACLs currently in-progress.

>* 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!!"
>
>  
>
Maybe we can come up with an automatic process for this or at least an
easier way to watch for the "cruft" we need to clear.

>* 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
>  
>
Overall, a good outline of what needs to happen.  The ACLs and page
structure should be high priorities.  We need to get people writing.  A
lot of experienced doc writers are going to hate the wiki, so we
certainly need to minimize how much the wiki is required, but a lot of
inexperienced people will prefer the wiki, if for nothing more than
ignorance.  If we can at least source basic documents from them that
way, it is worth while.  Anything that gets more people writing will get
a +1 from me.

-- 
Patrick "The N-Man" Barnes
nman64 at n-man.com

www.n-man.com
-- 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050823/f59a181d/attachment.sig>