Wiki source for StyleGuide


Show raw source

>>Writing on a wiki proceeds from ThreadMode to DocumentMode by way of RefactoringPages. These modes are not HardAndFastRules but ways of approaching a TextInProgress.>>====Weblogs and Wikis Style Guide====
Because a wiki is a collaborative space, a style guide is a guide to the customs of the culture as much as it is a guide to writing.

=== General Procedures ===
Start pages either in ThreadMode or DocumentMode, or a bit of both. It doesn't matter where we start. Find a place for a WikiWord and go.

- For DocumentMode, we use a clear but informal, third-person, active voice. Expect others to elaborate or complete your writing. Write so that others //can// elaborate. If you wish, you can sign your WikiName at the bottom of the DocumentMode section as a contributer. Or not. Up to you. This page is an example of DocumentMode.

- For ThreadMode, we use first person. You may sign your entries, or remain anonymous.

- On this wiki, we place the DocumentMode section at the top of the page, followed by ThreadMode contributions. We use DoubleLines (two lines of four dashes) to separate DocumentMode from ThreadMode on the same page. This convention is not absolute, however, and we find that writers add comments and questions to DocumentMode sections. This is a Good Thing, and writers can refactor the page to address the embedded comment. But as a thread gets long, move it below the DoubleLines.

- Add notes, comments, first-person anecdotes, questions, personal opinions in ThreadMode where they seem to fit best on the page. Sign them, or not. Expect someone to review ThreadMode contributions occasionally, to refactor them, reorganize them, and roll them into DocumentMode. That someone is you.

- The conventions of citation and quotation apply on a wiki. When you borrow or quote, cite; and if the source is online, link to it. Use only those images you have permission to use, and give credit.

- Expect to have your words folded into refactorings as the page develops towards DocumentMode. Be flattered when it happens. We are.

=== Jumping In: Contributing ===
Newcomers to a wiki are often apprehensive about contributing. [more] The material above the DoubleLine is DocumentMode and is owned by the wiki: it represents the collective effort of all contributors and is expected to change. The material below the DoubleLine is considered discussion and dissent. Our aim is not to quiet dissent but to incorporate it into DocumentMode. Wikis don't work by consent but by dissent, discussion, synthesis.

It takes nerve to refactor what's come before. Here are some techniques.

~- Leave the signed entry. Refactor the ideas into the DocumentMode above the line, but leave the original signed material.
~- Review the threads until you see a pattern or structure to the comments and discussion. Summarize or synthesize that pattern and roll it into the DocumentMode.
~- ...

''Let's add a WelcomeRitual. And practice good [[http://c2.com/cgi/wiki?DialoguePractices Dialogue Practices]]Review and draft our own DialoguePractices.'' See WikiWallflowers

=== Rhetorical Manner ===

~ There are people for whom, in the strictest of self-interest, WikiWiki is a learning place. For some it is a knowledge base. For others it is a forum for debate. All find something of value. Ward Cunningham and Bo Leuf, TheWikiWay, p ?

We encourage a variety of rhetorical manners on this wiki, from lectures to casual discussion. Think of moving from room to room at a party. In each room, there's an exchange going on. In one room, one person holds the floor with a thoughtful, balanced lecture. In another, a small group is having a heated debate. In another, a group of strangers are exchanging the first tentative remarks about an issue of the day.

When you encounter a page, take a moment to consider the rhetorical manner that seems at work. What's going on here? Is this a formal debate? A sermon? A casual exchange of views? A dialogue? Adjust your rhetorical approach and manner accordingly. Or refactor the page towards a new rhetorical manner.

=== Nix to NeutralPOV ===
We're not about NPOV. Balance, consideration, decorum, openness, and BalconyView. But Wikipedia does NPOV, so we don't need to. We use //we//, not //I//, and not the invisible I of the passive, nor the invisible mass of "some people." We get in close enough to name names.

>>We've found that rhetorical moves that work well in oratory may actually get in the way in a collaborative space, preventing development and stifling discourse. Since at root, the wiki is not a space for hortatory, AgonisticWriting so much as a space for DeliberativeWriting, its development would favor rhetorical strategies of invention and deliberation over sermons, standup routines, and lectures. But over time, even the most agonistic missive will be moderated by responses and refactored into DocumentMode. If you get on a soapbox, expect a response. Expect to be refactored into moderation.>>=== Some general guidelines ===

Applying some rhetorical guidelines will keep the discussion moving forward.

~- Civility and understatement give contributors space to work. Namecalling and writing to annoy others spoils the pool. Write to make this a comfortable place to work.
~- There doesn't seem to be much profit in writing off the cuff on a wiki - even in ThreadMode. WikiStyle is a thoughtful, crafted style.
~- Concision is noble. Concision keeps the signal to noise ratio up (high signal, low noise), and it allows others to contribute.
~- ClichedThought (yet another iteration of WhatEverybodyAlreadyKnows) contributes little and can get in the way of development. While clich├ęd thought may be merely annoying in prose, it is a burden on a wiki, increasing noise while contributing little. Have something to say.
~- On a wiki, ideas rule. Posing and posturing offer little to development. When the prose is more about the writer than the subject, the writer gets in the way of the ideas.

=== strategies for development: moving the thread along ===
Even when you have little to say, you can contribute to the thread.

~- Structure the page
~- Reorganize the page
~- Trim ThreadMode comments to bring the gist forward so others can respond to it.
~- Refactor the page to DocumentMode

>>SunirShah writes, 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 [[http://www.usemod.com/cgi-bin/mb.pl?StyleGuide Meatball Wiki StyleGuide]]>>=== Getting Started ===
You're reading and you see a place in an existing page where a concept or idea needs development, counterpoint, clarification, explanation, or variation. You add a WikiWord to the text. Sometimes the words you want are already in the text, JustWaitingForDevelopment. Just jam 'em together. Follow the link to the new node and get started. Or leave the node for someone else to develop.

You can also leave open-ended WikiWords in your own text to invite comment or elaboration from others. A later reader will see the ? and be prompted to provide this content.

When a topic worth pursuing arises in a face to face conversation, we make a mental note to move the conversation back to the topic later. We do the same on this wiki by leaving and placing WikiWords in ThreadMode entries, taking care to maintain the writer's meaning.

=== Structuring and Restructuring Pages ===
Structure on wiki pages develops as the ideas develop, and is developed to bring out the ideas rather than for the sake of form. RefactoringPages involves seeing structure in the page.

~- Heads and subheads help create structure which helps create meaning. Structure pages using TextFormattingRules.
~- Bulleted lists can be AGoodThing. But don't let lists stand in for DiscursiveProse. Use lists as an element of DiscursiveProse.
~- Page Summaries We like to use page summaries on this wiki to help others quickly get oriented to the page. Post a page summary at the top of the page, laying out what the page will cover or do. Change the summary as the page evolves. We also use this summary area to list what needs to be done on the page.
~- Summarizing the main points of a page can provide a fresh start for refactoring.
~- Links: Use descriptive link text and consider where the links might be placed on the page: in line or called out.

=== RefactoringPages ===
Refactor pages when the threads become involved and synthesis is possible. Complete rewrites that condense the essentials of many different contributions are one of the charcteristics of wiki life. See RefactoringPages.

~- Refactoring might entail finding a PagePattern to help organize the content. Heads and subheads signal the PagePattern.
~- Refactor pages to emphasize the structure of ideas, not the chronology of contribution.
~- Roll ThreadMode material and ideas into DocumentMode. Recast the prose in a clear, concise, third-person voice, maintaining the ideas but giving them structure.
~- A page can be broken up into several pages if the threads seem to become to convoluted and need clarification.

=== Prose Style ===
We figure readers can and will read intellegently and will spend some energy reading - if the pay-off is worth it. Wikis are places of thought and consideration, not hit and run. Short and sweet have a place, but really gain their meaning in context of considered and nuanced.

Use complex sentences to articulate complex ideas. We don't want to limit the range of expression by banning complex-compound sentences or limiting punctuation. So we aren't adverse to complex but clear sentences, employing semi-colons, colons, dashes, even ellipses where appropriate to make meaning.

=== Paragraphs ===
Paragraphs are meaningful units of discourse. They can be long and developed, short and pithy, and in between. Paragraph.

=== Editing ===
~- If you see an infelicity, a typo, a misspelling, fix it silently.
~- Edit sentences and paragraphs for concision and clarity.
----
----
StyleGuideNotes: LindsayLarson. Notes on a face to face discussion on wiki writing, 3 Nov, 2004.

A mighty fine [[http://www.usemod.com/cgi-bin/mb.pl?StyleGuide StyleGuide at Meatball]]

sources: Draft borrowed from [[http://www.weblogKitchen.com/wiki.cgi?StyleGuide the style guide at weblogKitchen.com]]. But in good WikiFashion, the original draft is now more obscured than visible. I've taken [[http://www.seedwiki.com/page.cfm?doc=Wiki%20Good%20Style&wikiid=1231&wpid=77845 Wiki Good Style]] as a model for this refactoring. MorganMC

See also
- [[http://biro.erhetoric.org/wikka.php?wakka=NotesTowardsARhetoricOfWikis Notes Towards a Rhetoric of Wiki]], on Morgan's wiki at biro.erhetoric.org.
- CollaborationConventions
- CollaborateRadically

----
----
Have a look at the UC Davis style guide: http://daviswiki.org/Wiki_Style_Guide Not to emulate but as a comparison.

----
CategoryWiki CategoryWikiHandbook
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki