Wiki Essentials

Wiki EssentialsWhat you need to know

http://wiki.mismo.org

2 Table of Contents

Table of Contents• What is a Wiki?• Some Common Wikis• Important Wiki Concepts• Wiki’s Role in MISMO• Getting Around

– Left Menu– Search/Quick Navigation– Document Tabs– Top Menu

• Getting Setup• Creating Wiki pages• Editing Pages

– Two Editor Options– Some Wiki Syntax– Plain Text Editor– Side-by-Side Example– WikiWizard (WYSIWYG Editor)

• Formatting– Page Structure– Bulleted & Numbered Lists– Links Expanded– Tables & Tabs

• Plugins• Customizing & Extending the

Wiki• Best Practices• Most Common Formatting

Rules

3 Table of Contents

What is a Wiki?• “wiki” comes from the Hawaiian word which

means “fast”

• You can see a pretty good definition at Wikipedia, but it is basically a web application that supports collaborative authoring of Web pages. The model is very dynamic and non-hierarchical. Wikis are extremely useful in places where the relationships between web pages are non pre-defined.

4 Table of Contents

Some Common Wikis• There are thousands of Wikis in use today. Wikis can provide a

benefit any time there is a community of people with a shared interest in some subject.

– Wikipedia (http://en.wikipedia.org)• The granddaddy of them all. Wikipedia is an encyclopedia of everything

– LostWiki (http://lostwiki.abc.com)• ABC's Wiki on the TV show "Lost".

– Solar Cooking Site (http://solarcooking.wikia.com)• A site about solar cooking

– Wookieepedia (http://starwars.wikia.com)• Star Wars encyclopedia and all things Wookie.

5 Table of Contents

Important Wiki Concepts• Keyword-based/Topic-based documents

– Documents have an absolute name indicating their topic– Example document names;

• PhotoSynthesis• NamespaceApproach• XmlSchema

– Expectation is that there is single page for a given topic.

• Reuse (References Rather than Embedding)– When one topic needs to reference another, links are used rather than repeating

content• PhotoSynthesis -> Chlorophyll• NamespaceApproach -> LinkingApproach• XmlSchema -> Internationalization

• Linking– Lightweight Approach – links just use the keyword rather than complete URLs– Links can be made in anticipation of content that is not there

6 Table of Contents

Wiki Concepts (cont…)• Flat Repository

– No assumptions about hierarchy and relationships among documents

• Edit in Place– Changing content is easy, is done right in the same browser that is used for

navigating and viewing. – Source Control happens automatically– Pages compared on check-in to make sure no collision occurs

• Lightweight Syntax– Markup is lightweight and text based.– Rendering with different looks and feels done with styles– Can edit with text editor or WSIWYG editor

7 Table of Contents

Wiki's Role in MISMO• For Managing

– I-Guides– Engineering Guidelines– Commonly referenced documentation– Rapidly changing documents like task lists

• Changing the Process– More collaboration– Smaller more manageable topics

• Re-use and Modularity– Lighter-Weight process– More inter-linking

• Why not Sharepoint?– Strict Hierarchy versus web of data– Sharepoint is subscriber-only– Wiki has more comprehensive linking support

8 Table of Contents

Getting AroundLeft Menu Breadcrumbs

Main Content Area

Search/Quick Navigation

Top MenuDocument Tabs

9 Table of Contents

Left Menu

• This is a nod to hierarchy

• Contains common starting points for navigating the Wiki

• Content to be finalized

10 Table of Contents

Search/Quick Navigation

• Allows search on document names and content• In Upper right Corner

Basic Mouse-Over Search for term “Secondary”

11 Table of Contents

Document Tabs

• View Tab– Displays main content of the page & available menus

• Attach Tab– Shows list of existing attachments and allows authenticated

users to upload and manage documents.

12 Table of Contents

Document Tabs: Info Tab

• Version History Sub-Tab– Note: you can link to specific versions

• Incoming Links Sub-Tab• Outgoing Links Sub-Tab

13 Table of Contents

Top Menu

• Home– Link to the MISMO Wiki Home Page

• Edit– Only available if you are logged in

• Comment?– Option to add a comment to a page

• Index– Displays an Alphabetical list of all documents (pages)

• Changes– Displays recent changes for entire MISMO Wiki site, not a particular document

• Prefs– Allows you to change your user preferences

• Login/Logout– Allows you to Login to edit or Logout from the wiki– Login is not required to view pages

14 Table of Contents

Getting Set up• Your Preferences

– Can adjust setting– Most important thing is your “skin”

• Controls look and feel of site

• Logging in– You must be logged into edit content– On the honor system – not tied to formal security– Full names should be used

• “JohnSmith”, not “SurferBoy312”

15 Table of Contents

Creating Wiki Pages• Start with References

– Pages are only useful if people can find them– Is your page related to pages that exist already?– Linking to non-existent page creates a placeholder

• Page Name Standards – Wiki uses MixedCamelCase – For example “MyTopicPage”– Plurals don’t matter

• Create a link in Sandbox page – http://wiki.mismo.org/MISMOWiki/Wiki.jsp?page=Sandbox

• Links take the form [<linktext>] or [<displaytext>|<linktext>]– *[MyTopicPage]– *[My Topic Page]– *[My Topic|MyTopicPage]– *[MyTopicPages]

16 Table of Contents

Editing Pages• Follow “Edit” link in the Top Menu to edit existing

pages (link only appears when logged in).

• Must use Wiki markup. For help when editing a page, a “Help” Document tab appears with the most common formatting rules.

• Complete Syntax Guide in Wiki document TextFormattingRules – http://wiki.mismo.org/MISMOWiki/Wiki.jsp?page=Text

FormattingRules

17 Table of Contents

Two Editor Options

• Plain Text Editor• WikiWizard

18 Table of Contents

Some Wiki Syntax• Formatting Text

• Bold by bracketing with “__”: “__BoldText__”• Italics by bracketing with “’’’”: “’’’ItalicText’’’”• CSS for complex formatting:

• %%(color:red) This text is red. %%

• Embedded Images• Just create a link to them• Example:

• [{Image src='BREWDiagram.jpg' width='900' height='800‘ align='center' }]

19 Table of Contents

Plain Text Editor

• Must learn simple wiki Markup– See sample on next slide

• Screen background will change colors (usually blue)

“Plain” editor is selected

20 Table of Contents

Side By Side Example

• Edit in Place– Changing content is easy, is

done right in the same browser that is used for navigating and viewing.

– Source Control happens automatically

– Pages compared on check-in to make sure no collision occurs

• Lightweight Syntax– Markup is lightweight and text

based.– Rendering with different looks

and feels done with styles– Can edit with text editor or

WYSIWYG editor

*__Edit in Place__**Changing content is easy, is done

right in the same browser that is used for navigating and viewing.

**Source Control happens automatically

**Pages compared on check-in to make sure no collision occurs

*’’Lightweight Syntax’’**Markup is lightweight and text

based.**Rendering with different looks and

feels done with styles**Can edit with text editor or

[WYSIWYG|wikipedia:Wysiwyg] editor

!!!Side By Side Example

21 Table of Contents

WikiWizard

• WYSIWYG (what you see is what you get) editor• Useful when working with tables

“WikiWizard” editor selected

22 Table of Contents

WikiWizard w/ Tables

||Date||Agenda ||Minutes ||Type ||Discussion ||Documents|July 10, 2007|[Agenda|Agenda071007]|[Minutes|Minutes071007]|Conference Call|[Discussion|Meeting071007Discussion]| [Bulk Bid Use Case |https://sharepoint.mismo.org/secondary/Shared%20Documents/3.x%20Work/Pricing/Bulk%20Bid%20Pricing/Bid%20Process%20Business%20Use%20Case%20Draft%2020070709.doc], [Bulk Bid Pricing Worksheet|https://sharepoint.mismo.org/secondary/Shared%20Documents/3.x%20Work/Pricing/Bulk%20Bid%20Pricing/BulkBidPricingWorksheet.xls]|June 19, 2007|[Agenda|Agenda061907]|[Minutes|Minutes061907]|Conference

Equivalent Plain Text Editor

23 Table of Contents

Page Structure

• Headers are used for high level page structure– Headers visually partition a page– Headers create Anchors for direct links to sub-topics– Headers drive the table of contents– Syntax

Wiki Markup What You See• !!!Biggest Header Biggest Header• !!Medium Header Medium Header• !Smaller Header Smaller Header

24 Table of Contents

Bulleted and Numbered Lists

Wiki Markup *Parent Bullet

**Child Bullet***Grandchild Bullet

# Parent Bullet ##Child Bullet 1##Child Bullet 2###Grandchild Bullet

What You See• Parent Bullet

– Child Bullet• Grandchild Bullet

1. Parent Bullet1. Child Bullet 12. Child Bullet 21. Grandchild Bullet

• * and # for bulleted and numbered lists respectively

• Repeat for indentation

25 Table of Contents

Links Expanded• Link to a local wiki page

• Syntax: [<displayname>|<page>] or [<page>]• Example: [Mismo Word Guidelines|ClassWords] Mismo Word Guidelines

• Link to an Attachment• Syntax: [<displayname>|<attachment name>]• Example: [Project Schedule|schedule.xls] Project Schedule

• Page subtopic • Syntax: [<displayname>|<page>#<header>]• Example: [Guideline|Terms#Guideline] Guideline

• Foreign Links• Syntax: [<displayname>|<url>]• Example: [SISAC|http://www.sisac.org/default.html] SISAC

• InterWiki Links• Assumes administrator has set up alias• Syntax: [<displayname>|<wikiname>:<page>]• Example: [Mortgage|wikipedia:Mortgage] Mortgage

What You See

26 Table of Contents

Tables & Tabs• Tables

– Example||Header 1||Header2|Row1Col1|Row1Col2|Row2Col1|Row2Col2

– Will make table sortable by column headers if you enclose within %%sortable %%

– Can be more easily maintained with WikiWizard

• Tabs– Example

%%tabbedSection%%tab-Tab1<Tab 1 content>%%%%tab-Tab2<Tab 2 content>%%

Header 1 Header2Row1Col1 Row1Col2Row2Col1 Row2Col2

27 Table of Contents

Plugins• When using any plugin, the syntax is as follows:

– [{<PluginName>}]

• Some Important Plugins– Table of Contents

• Displays TOC with links to sections. • Based on header names.• [{TableOfContents}]

– InsertPage Plugin• Embeds the content of another page in this one• [{InsertPage page=‘<PageName>'}]

Section Menu

28 Table of Contents

Customizing & Extending the Wiki• We can create custom Plugins

• We can create New Templates and skins

29 Table of Contents

Best Practices• Keep pages small and on-topic

• Create obvious page names

• Don’t re-invent the wheel (look for similar pages before making a new one)

• Compose complex “documents” from small topics

• Don’t hesitate to put drafts out there, Refactor, redo later

• Work the Undefined Pages

• Create Page references for concepts that need to be fleshed out

30 Table of Contents

Most Common Formatting Rules