StyleGuide

MeatballWiki | RecentChanges | Random Page | Indices | Categories

Golden rule

: Write for the reader, but remember that you are also a reader; so, edit the text until it becomes useful to yourself as well. Respect others' ideas of what is useful. Sometimes this is best done by simply creating a new page, but not usually.

For team wikis, the last line changes to...

: Sometimes this is best done by simply creating a new page to take notes, but not always.

Description

The art of being a genius, a rock star, a leader is not having an original idea. We all have original ideas, many good. The art is in communicating those ideas effectively. Regarding the first half, one must communicate: one must feel compelled to speak, write, or perform. Regarding the second, one must be convincing, and that means realizing you are speaking to someone else, TheAudience, who are not sympathetic. Not only do you have to be convincing, but you have to organize and structure your ideas well because no one else has the time to do it for you.

The art of communicating effectively is merely about learning the conventions that everyone expects. If you follow the rules, you will not unintentionally surprise people--unless you actively mean to surprise them by breaking the rules. TheAudience will be focused on what you are saying because they are not distracted with how you are saying it. Moreover, if you structure your thought well, TheAudience will more readily accept the idea because it will be simpler for them to internalize.

Therefore, it is in the best interest of any successful OnlineCommunity to generate a StyleGuide to collect the general wisdom of how to communicate effectively. Use the style guide to teach others how to improve their writing. Use it as a yard stick to measure your own writing. Use it as a method to improve the stature of the community as a whole amongst the wider public audience, and thereby improve the stature of all the active CommunityMembers.

: If I'd had more time, this story would have been shorter.
: --Paraphrase of a translation of Blaise Pascal, usually misattributed to Mark Twain.

The StyleGuide is always incomplete because writing well is an incomplete science, and MeatballWiki is not necessarily the authority on writing. Some of the ideas are particular to wikis. MeatballWiki is at least an authority on writing on MeatballWiki. New contributors should consider what we have learnt about how this medium affects their writing styles. So far, this is what we have learnt.

SpellingConventions simplify both the readers' lives and the authors' jobs. While spelling may seem like a matter of personal style, that must be tempered with your readers' patience.

AbbreviationsAreEvil because they are misspellings on purpose. That causes confusion because readers then feel like it is their responsibility to learn what is really only the laziness of the author.

AvoidClutterLinks because they are land mines of confusion.

ShallowPages aren't worth the time they take to click on.

TemporalContext in writing requires care because time is a funny thing on a wiki. We have both the WikiNow and RecentChanges to contend with.

Avoid the JargonProblem by understanding its nature.

ReplyToTheWholePost. Don't interrupt others.

KillYourDarlings. Have courage to eliminate of words and ideas you're in love with if they aren't adding anything to the whole.

Other styles

We occasionally describe other styles of writing, although we don't necessarily recommend them for MeatballWiki.

NeutralPointOfView, the style of WikiPedia, which would probably be better named "no point of view."
EPrimeLanguage writes without using the verb To Be in order to eliminate false categorizations and other fallacies introduced with this verb.
RoyalWe written on a wiki from the mouth of the leader acts as simple democratic way to describe policy quickly without denying other community members the ability to dissent.

Rule Of Thumb

Here's a little game I play:

Write, then delete and simplify as much as possible. Use smaller words. Remove words that add no value. Delete rhetorical window dressing; good rhetoric is not separated from the message.

When you get good at this, you will find your sense of rhythm will improve and, with it, your rhetorical style. Most sentences sound the best when they are crisp but meaningful. So do Wiki page names.

You'd be surprised how long it can take me to write a three line post. Sometimes you can watch me edit the same text many times in a row. It takes effort, but it's worth it because the resulting text is clean and crisp. -- SunirShah

Splitting Pages

: How long is too long before it merits its own page? -- SteveWhite?
: You never know until it splits. -- AlexSchroeder
: I'm going to try some tests to find effective limits. That's one of the reasons I am experimenting with Tables Of Content and other useMod capabilities. -- HansWobbe

When a page gets too long, consider reworking it, and putting parts on pages of their own.

Sentence Types

Sentences are classified according to their structure:

Simple sentences have one subject and one predicate. Either the subject, or the predicate, or both may be compound.
Compound sentences have at least two independent clauses, each of which has its own subject and predicate.
Complex sentences have one or more dependent clauses, and one independent clause.
Compound-complex sentences have at least two independent clauses (like the complex sentence).

Preferred Structure

Short sentences tend to have simple construction. That is a valuable consideration in the international market.

Avoid compound sentences. If necessary, use two sentences separately.

Approach complex sentences, with their subordinate clauses, prepositional phrases, and potentially misplaced modifiers, carefully. If it works, the results are great. If it does not, it can be dangerous.

Sentence fragments can be used in bulleted lists and in tables, but should never appear in text.

Person, Mood, and Voice

Write descriptive text in the present tense, third person, indicative mood, and active voice. In other words, write as if you were talking to someone, and use action verbs to describe events as they happen.

Example: The door interlock deactivates the REMOTE CONTROL switches when the door is open.

NOT: REMOTE CONTROL switches are deactivated by interlocks when the door is opened.

Write procedural text in the present tense, second person, imperative mood, and active voice.

Example: Drill mounting holes and bolt cabinet to wall.

NOT: A mounting hole should be drilled and the cabinet bolted to the wall.

Paragraphs

Think of the paragraph as the largest chunk of text the reader can handle at one time. The size of the paragraph, from a single line to many sentences, does not matter as much as the scope.

To be more effective, a paragraph must hold together such that all its sentences belong with each other. A paragraph must also show deliberate organization, so the reader is guided through, rather than being thrown into the text. Finally, a paragraph must be complete, with a unity that allows readers to look away after finishing the paragraph and be able to understand and remember what they just read.

Function

In fields other than technical writing, the functions of paragraphs vary with the type of writing, and with the technique and skill of the author.

For the technical writer, paragraphs generally perform one of the following functions:

Define (the scope of an operation or procedure or document, etc.)
Describe (the equipment, screen displays, settings, or calibrations, etc.)
Detail (parts numbers, tools needed, tube characteristics, etc.)
Direct (an operation, service procedure, steps in a checklist, etc.)

When you ask what a particular paragraph is doing, the answer should be one of these four functions. If a paragraph is performing two or more functions, it is too big, complex, and unfocused. A paragraph, remember, must show deliberate organization. Simply grouping sentences together in a block is not enough to create a paragraph.

Structure

The paragraph in technical writing has two parts - the focus and the support.

The focus, also called the topic sentence, is the purpose of the paragraph. The focus tells what the paragraph is about, and provides the basis on which the rest of the paragraph is based upon. It is most often a sentence, though it may be just a sentence fragment, such as the lead-in to a list. The focus is the first sentence in the paragraph. Paragraphs that start with a reference instruction, for example, "See Figure 3.2", will have the focus in the second sentence.

The support is the body of the paragraph, and contains details, steps, arguments, facts, and examples....

Document Mode vs. Thread Mode

Make sure you know the difference between DocumentMode and ThreadMode. Sometimes you find the two on one page: An idea at the top of the page, a horizontal line, and then a discussion. If the discussion grows and grows, the page is split into two: The first page has the idea, the second page has the discussion.

Therefore, don't start a thread in the middle of an elaboration. Quote a few words and discuss at the bottom of the page -- or refactor the idea. Don't transform documents into threads.

If discussion dies down, refactor it. Perhaps the discussion in itself has value, then keep it archived on another page. Often discussions can be summarized, when they are over.

How about giving users some explicite clues about the desired structure of the page? Like some note 'This page is in document mode' at the beginning? With some attached link to a description of the schema. Of course this can apply to other rules as well. -- ZbigniewLukasiak

Discussion Has Value

There's a heavy emphasis on anonymous DocumentMode on this site because this site is primarily a repository. However, after long arguments, sometimes people say interesting things. Not abstractly interesting, but humanly interesting. It could be personal testimony like anecdotes or opinions. Or it could be a particularly fluid rhetoric. In those cases, it's justifiable to preserve signed quotations because it's entertaining. This also recognizes the contribution of others in a positive way.

One method of reworking is the reduction of thread mode to its bare essence. Much loose conversation is filled with trivial words, or half ideas that are explored in detail elsewhere. Consider stripping the conversation to its bare simplicity, but let it remain a conversation.

This leaves room for incomplete ideas and objections. It's also legitimate to leave erroneous argument behind. This will provide the reader a dialogue she can follow that works through the argument. Combined with the reduction mention above, this is a powerful technique to bring a reader through a difficult concept. Mistakes are experiences too.

When reducing thread mode, consider making up names like Alice and Bob, or using interlocking anonymity: Use alternating italic and normal or indented and normal text.

Signing contributions

When you sign a contribution in a thread, use your name. --AlexSchroeder

When you are adding to a page without participating in a discussion, consider not signing your contribution or adding your signature to a list of contributors. This encourages refactoring.

When writing anonymous material, do not write in the first person. Conversely, whenever writing testimonial, sign your name. Often writing in the first person is not testimonial. In that case, write it formally (i.e. not in the first person).

Initials

Avoid using your initials to sign contributions. Initials are unclear, impersonal, obscure the practice of UseRealNames, and hinder later refactoring efforts. Either sign with your name or write anonymously.

In certain cases initials may be acceptable in order to maintain context in a threaded discussion, but only when you expect your contribution to disappear or be refactored soon. Consider using other means to separate distinct voices, such as italics and indentation.

Thread context

Thread context if often essential, even if the actual author is not. Leaving comments unsigned makes it difficult to follow the thread as each statement must stand on its own without the context of earlier statements. Sign contributions with initials when necessary to maintain thread context, unless you really want to your contribution to be marked with your name (i.e., not be anonymous). Think of your initials acting as markers of voice, but not of ego. See AnonymityVsPseudonymity.

It would be good if your first contribution in the thread was signed with your full UserName, and then initials used later as required - this is similar to the good style rule for first use of acronyms.

Therefore, when refactoring, treat initialled comments as more anonymous than signed comment, except when good sense should prevail.

But be careful when refactoring a ThreadMess that you don't zap the one and only fully expanded instance of a contributor's UserName. This can be difficult if the initial entry comment by a participant is of low quality/relevance. One approach to take is to move the UserName to another comment, replacing that contributors initials with their full UserName. Picking an initialled contribution that is also worthy (ie. unlikely to be refactored out), but which is also early in the thread (so as to avoid initials appearing before username), is what makes refactoring harder. Use a list of contributors instead.

Conventional typesetting as guide

Consider that the signing convention is the same convention you use when quoting others.

: Time flies like an arrow. Fruit flies like a banana. -- Groucho Marx

If you consider a wiki page to be a normal page (as in, of paper), then the writing conventions are essentially equivalent to what you'd use to layout a page in a book. When in doubt, write like you're writing a formal paper. The more you try to write like that, the more the site will average out to be something actually readable.

One big change or several small ones

When making many edits to a page, should one try to save the page only once (to minimize the impact of RecentChanges for those who use &all=1), or should one save the page many times so that the various edits can be more easily understood by looking at the diffs?

If you do one thing at a time, there is less chance you will make a mistake. Furthermore, people seldomly use all=1.

Fold see alsos

You will often see OutOfLineLinks floating around as "See also"s, including "contrast" or "compare" or "consider" or similar phraseology. While these are useful for tying pages together, and they are an acceptable style in many cases, it is even better to fold the see-also into the main body of the text as an Inlinelink, even as weakly as with a (cf.) reference in context, but better as Wiki:WikiGrammar. This may require writing more text. Good! It's clearer that way than just providing a link without the intended relationship explained. After all, a see-also is just a point form note. So, if you see a see-also and follow it, consider returning and writing down your impression of the relationship.

Additionally, BackLinks are also see-alsos, but even more hidden. You may want to write about their relationship to the page as well if you think that is relevant.

CategoryStyle CategoryRoadmap