Henry,
Here's the style guide, it should be good enough to post on the site. Of
course, it's open for the group's approval.
We'll be posting the final SiteGroups document in the next couple days. It
is an example of a document that uses the Midgard style.
Ron Parker
Mi-Recordz
www.mi-recordz.com
[EMAIL PROTECTED]
Be kind to animals, unless you're hungry.
STYLE GUIDE FOR MIDGARD WRITERS
Transparent Writing Style Creates Effortless Comprehension
The goal is to write a manual that's predictable for the reader. When a person studies
a topic, they learn the author's style of presenting data. When a manual has many
features and each one is presented with the same order of information, the reader
becomes capable of predicting where and how to find answers. Ultimately, the writing
becomes transparent so the reader can effortlessly comprehend the subject.
Inverted Pyramid Succinctly Introduces All Information
The first paragraph of every chapter or section must be written to succinctly
introduce all the concepts. Subsequent paragraphs provide detailed explanations of the
concepts that are introduced in the opening paragraph.
Consistent Organization Of Topics Eases Comprehension
The SiteGroup chapter of the Midgard manual demonstrates three topic sections for
organizing a document; they include Introduction, Configuration, and Usage.
Introduction:
*inverted pyramid, supplies the reader with an overall perspective
Configuration:
*inverted pyramid, leading to step-by-step directions, and when necessary uses a
bulleted list or graphic
Usage:
*inverted pyramid, then step-by-step directions which may lead to bulleted lists of
instructions and graphics
Headlines for Chapters, Sections
Every attempt should be made to write subject, verb and object constructions when
introducing chapters and sections:
*Midgard's Predictable Style Produces Effortless Comprehension
Headlines do not receive ending punctuation. The word "and" is replaced by a ",". In
general, the headline is built by perusing the opening paragraph for subject, verb and
objects which highlight the main points.
Tight Writing Equals Clarity
Each sentence should be an attempt to introduce one thought. The use of paranthesis to
introduce secondary thoughts should be avoided. It's better to treat secondary
thoughts as separate sentences.
Redundancy must be eliminated. Every extra word or repeated thought needs to be
omitted or rewritten.
Punctuation, Taken From Chicago Manual Style
Series comma (this, that, and the other).
Curly quotes and apostrophes (" " not " ") in regular text.
Straight quotes (" " and ' ' not " " ` ') in constant-width text and all code. Some
Unix commands use backticks (`), which must be preserved.
No period after list items unless one item forms a complete sentence (then use periods
for all items within that list, even fragments).
Closed em dashes-not surrounded by spaces.
The Chicago Manual style is our default.
Lowercase the first letter after a colon: this is how we do it.
--
This is The Midgard Project's mailing list. For more information,
please visit the project's web site at http://www.midgard-project.org
To unsubscribe the list, send an empty email message to address
[EMAIL PROTECTED]
