protect your docs like you do your source code [ an editorial ]

[Karsten Wade]

Would you put the editing of the kernel source into a Wiki?

Sounds extreme, but let me scare you even further.

In program source code, you *can* use different code to get the same
results.  There are always lots of arguments for and against certain
solutions, but it is possible to use different ones.

In written language, you can move a single comma and have a sentence of
an entirely different meaning.  There are entire books filled with
examples[1].  You may have a favorite one you want to share.  We can
frame this argument as, "The meaning is in the syntax."

Dropping a single character can have unexpected and REALLY BAD
consequences:

  rm *~

Just don't drop the ~.

Because users rely upon our documentation, from manual pages to PDF
guides, we have to exert the same level of stewardship as we do for the
project source code.  This does occur for manual pages, and it is the
scope of the Documentation Project to consider it at all levels.

This little editorial is just to set the stage for further discussions
of where documentation lives and how it is produced.  Personally, I'm
open to solutions, and so is the Documentation Project.

However, the stylist in me often hates Wikis.  Elevating a raw Wiki is
like sucking in all of CPAN and calling it the Fedora Perl Project.

For the moment, we have a process that we can be _responsible_ for.
Wielding the power of language, right?

We would need a new process for Wiki documentation to be even feasible.
By it's nature, such a process would be anti-Wiki.

For example, a process can be created using a Wiki, with authored pages
going through a workflow or some kind of upstreaming through editors.
Okay, really, that's a CMS.  If we can tack one onto the Wiki, cool.
I'd dig a way to graduate Wiki pages to canonical in the CMS.  Keep a
good Wiki page, we'll make it ThePage.  But it's not Wiki anymore,
because an editor has to check it first before it goes live.
Schroedinger's Wiki.

At least, that is what I gather from Wiki proponents.  Reduction of
control = not MyWiki!

This is just for the record. :)

- Karsten, who couldn't find room for this quote:

"A Wiki is like casual sex, you get to have your fun and leave behind
only your ScreenName."

[1] Eats, Shoots & Leaves
http://www.amazon.com/exec/obidos/tg/detail/-/1592400876/103-6883807-2623...

Punctuation quiz:
http://eatsshootsandleaves.com/ESLquiz.html

-- 
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/

[Karsten Wade]

Oh, here is an example of Wiki being well (ab)used.  Kudos to the work
involved in making this useful:

http://developer.mozilla.org/en/docs/Main_Page

On Mon, 2005-08-15 at 11:24 -0700, Karsten Wade wrote:
>  Would you put the editing of the kernel source into a Wiki?
>  
>  Sounds extreme, but let me scare you even further.
>  
>  In program source code, you *can* use different code to get the same
>  results.  There are always lots of arguments for and against certain
>  solutions, but it is possible to use different ones.
>  
>  In written language, you can move a single comma and have a sentence of
>  an entirely different meaning.  There are entire books filled with
>  examples[1].  You may have a favorite one you want to share.  We can
>  frame this argument as, "The meaning is in the syntax."
>  
>  Dropping a single character can have unexpected and REALLY BAD
>  consequences:
>  
>    rm *~
>  
>  Just don't drop the ~.
>  
>  Because users rely upon our documentation, from manual pages to PDF
>  guides, we have to exert the same level of stewardship as we do for the
>  project source code.  This does occur for manual pages, and it is the
>  scope of the Documentation Project to consider it at all levels.
>  
>  This little editorial is just to set the stage for further discussions
>  of where documentation lives and how it is produced.  Personally, I'm
>  open to solutions, and so is the Documentation Project.
>  
>  However, the stylist in me often hates Wikis.  Elevating a raw Wiki is
>  like sucking in all of CPAN and calling it the Fedora Perl Project.
>  
>  For the moment, we have a process that we can be _responsible_ for.
>  Wielding the power of language, right?
>  
>  We would need a new process for Wiki documentation to be even feasible.
>  By it's nature, such a process would be anti-Wiki.
>  
>  For example, a process can be created using a Wiki, with authored pages
>  going through a workflow or some kind of upstreaming through editors.
>  Okay, really, that's a CMS.  If we can tack one onto the Wiki, cool.
>  I'd dig a way to graduate Wiki pages to canonical in the CMS.  Keep a
>  good Wiki page, we'll make it ThePage.  But it's not Wiki anymore,
>  because an editor has to check it first before it goes live.
>  Schroedinger's Wiki.
>  
>  At least, that is what I gather from Wiki proponents.  Reduction of
>  control = not MyWiki!
>  
>  This is just for the record. :)
>  
>  - Karsten, who couldn't find room for this quote:
>  
>  "A Wiki is like casual sex, you get to have your fun and leave behind
>  only your ScreenName."
>  
>  [1] Eats, Shoots & Leaves
>  http://www.amazon.com/exec/obidos/tg/detail/-/1592400876/103-6883807-2623...
>  
>  Punctuation quiz:
>  http://eatsshootsandleaves.com/ESLquiz.html
>  
>  --
>  Fedora-marketing-list mailing list
>  Fedora-marketing-list(a)redhat.com
>  http://www.redhat.com/mailman/listinfo/fedora-marketing-list 
-- 
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/