[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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



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-2623068?v=glance
> 
> Punctuation quiz:
> http://eatsshootsandleaves.com/ESLquiz.html
> 
> --
> Fedora-marketing-list mailing list
> Fedora-marketing-list 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/

Attachment: signature.asc
Description: This is a digitally signed message part


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]