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:
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...