Wiki starting points? Drafts...

[Paul W. Frields]

On Wed, 2007-05-02 at 16:16 -0700, Karsten Wade wrote:
> On Mon, 2007-04-30 at 13:52 -0400, Paul W. Frields wrote: 
> > On Mon, 2007-04-30 at 08:47 -0700, Karsten Wade wrote:
> 
> > Fortunately, we also have a Style Guide which documents grammar, usage,
> > etc. for use in the official docs:
> > 
> > http://fedoraproject.org/wiki/DocsProject/StyleGuide 
> 
> Yes, but it doesn't cover voice[1].  We could set an overall voice that
> is a little different from e.g. traditional corporate technical content.
> Here are some that I could see us adopting:
> 
> * Jokey (light-hearted)
> * Casual (mildly jokey, addition of more pronouns)
> * Metal ("This guide teaches you how to *brutalize* your Fedora
> install...")
> 
> [1] Voice is the tone that writing takes.  It is the overall tone
> (sarcastic, excited, didactic, bored, informative, etc.).  It is also
> the individual character, which usually comes from a single writer (Neil
> Gaiman's voice is different from Stephen King's, Neal Stephenson's, and
> H.L. Mencken's.) 

I know which one I'm going to use... BESERKER!!!   ;-D

> > And don't forget that we can also update our Jargon Buster with these
> > terms, including a citation to Wikipedia, et al.
> 
> Are we comfortable with setting a requirement for inclusion in the
> Fedora Glossary (was Jargon Buster)?  Such as, "Include the term if the
> term has a special meaning in Fedora that is different or in addition to
> a meaning found in an upstream dictionary/glossary."  For example, "yum
> repo" and "yum repository" could use a canonical definition.

+1.

> > > Heh, heh ... now that this has come up on list a few times recently
> > > (refer to the archives for more of the same), maybe I need to write all
> > > this up at DocsProject/Screenshots. :)
> > 
> > How about in the Style Guide?  Currently this is in the Documentation
> > Guide, but if it doesn't fit we could yank it from there and link to it
> > instead.
> 
> Sure, StyleGuide.
> 
> Maybe we'll eventually pick the Documentation Guide of all the meat and
> bury the carcass?
> 
> It's not that the content isn't relevant, it's that it has found its way
> into more relevant or actively maintained places.

I think the main problem is that our toolchain is like much of Fedora
development, and changes faster than the docs can keep up.  Since this
particular doc is more or less *about* those tools, built *by* those
tools, it's exponentially harder to keep updated.

This may get easier in a XHTML <-> DocBook/XML Plone-y world...  In the
meantime, sure, cutting this down to size would be good.  I've done a
big update in the module structure area, but it probably needs new work
since there are changes made in just the last 30 days that affect it.
See, there you go...

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- 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/20070502/866a1589/attachment.sig>