Good Style

Write only factual information.

Give concrete advice, rather than abstract.

Make editing and elaboration easier by avoiding the use of "I" where possible (except in your Wiki Home Page).

Write and sign first-person accounts when reporting experiences and opinions not easily reduced to facts or objective advice.

Place words where they are easy to read; this is not always at the bottom, but they should not be placed before the "Opening Statement".

Respect the freedom you have been given.

Edit pages to emphasize the flow of ideas, not the order in which they were contributed.

Be concise.

Stay On Topic for the page.

Use language you'd be comfortable reading out loud - use versus utilize - and keep it simple. Simple language often communicates better.

Check for spelling and grammar errors - errors detract from the content.

Edit only when you think a page is lacking - don't just sign your name at the bottom of every page.

Delete only if doing so adds value.

Remember, if you want a nice page, make one.

Don't say things that are likely to make others mad. Practice civility and understatement.

Above all, be good, and play nice!


The following additional points are true, useful and relevant, but are not specifically about style:

The server has very simple Text Formatting Rules. Start each line without spaces, and separate paragraphs with a blank line. You can run capitalized words together to make Wiki Links.

Use Horizontal Separators to make things easier to read. Lots of different comments with no separation can otherwise be confusing.

As a visitor to this site or editor of this page, you have some responsibility; the responsibility is "Spirit of Freedom and Spirit of Quality". Everybody can contribute constructively by not contributing when he/she doesn't have anything to contribute. Learn what John Cage didn't.


Write only factual information.

How does someone distinguish between fact and theory, between opinion and authority? See Most Holy Wars Tied To Psychology and Discipline Envy. Personal opinion is unavoidable, but that does not absolve you from aiming for objectivity.

Where differences arise, use wording that clarifies the source. Stating an opinion is factual when phrased as "According to <source>, ..."

Writing in the past tense helps some of us to stick to the facts. :-) Writing without past or future tense (i.e., in the NOW) helps the truth come out. :-)


Re: "Write only factual information." - Does this exclude anecdotes? Software engineering lacks both in theory and in empirical studies outside of machine performance issues. It's largely still a dark art. If we followed that rule, this wiki would be nearly empty. Anecdotes are almost all we have to go on.

No, it includes anecdotes as long as they're true. It excludes lies and fiction.



See original on c2.com