Essential Wiki

Webs and Topics

See also:

Start presentation

Slide 1: Essential Wiki - Webs & Topics

http://wiki.cfcl.com/bin/view/Help/WikiTraining

Slide 2: What's Covered

  • What's a Wiki?
  • What's TWiki / Foswiki?
  • Webs and Topics
  • Working With Topics
    • Creating
    • Viewing
    • More Topic Actions
  • Editing
  • Attachments
  • Appendix 1: Personal Customizations
  • Appendix 2: Managing Content

Slide 3: What You Can Expect

Become an "Informed Consumer"

These training presentations won't turn you into you a Wiki expert in a few hours. However, you can expect to gain new perspective, hear about a few tips and tricks, add some insights, and see many examples.

We also hope you'll learn at least one new thing you didn't know before!

Slide 4: Who Are You?

  • What's your experience with wikis?

  • Experiences with TWiki or Foswiki?

  • HTML? JavaScript? CSS?

  • Are there any specific things you'd like to see covered in this session?

Slide 5: What's a Wiki?

A wiki is
  • a Web-based collaboration platform
    • that lets you and all other users write, place pictures, and post links
      • anywhere on any page.
In most cases, this means that anyone can edit anything.

A wiki is
  • Just a program
  • A kind of editor for web pages
  • Accessed using your favorite browser
    • (Firefox recommended)

TWiki and Foswiki are both wikis.

Slide 6: What Isn't a Wiki?

You don't need to...
  • Install additional software
  • Learn HTML
  • Wait for a designated webmaster to upload your files
  • Make a request to IT
  • Ask permission

See: WikiWhy.

Slide 7: Wiki History

  • The word "wiki" was coined in 1994
    • For the first wiki program: WikiWikiWeb
    • Created by Ward Cunningham

  • Based on a Hawaiian word for "fast".

"I chose wiki-wiki as an alliterative substitute for 'quick' and thereby avoided naming this stuff quick-web." -- Ward Cunningham

Cunningham was inspired in part by Apple's HyperCard. He also developed ideas from Vannevar Bush, allowing users to "comment on and change one another's text".

In the early 2000s, wikis were increasingly adopted by organizations as collaborative software. Common uses included project communication, intranet web access, and documentation, initially for technical users. Today some companies use wikis as their primary collaborative software and as a replacement for static web pages. There may be greater use of wikis behind firewalls than on the Internet.

On March 15, 2007, the word "wiki" entered the online version of the Oxford English Dictionary.

ref: Wiki.

Slide 8: Many Wikis Available

Hundreds of wikis are currently available, each with different features. Some are simple; some are powerful. All allow "regular" people to create web pages that can be viewed on the Internet or a company intranet. TWiki and Foswiki are just two available wikis.

Examples:
  • pbWiki
  • TiddlyWiki
  • Confluence
  • Wetpaint
  • Socialtext
  • MediaWiki (used by Wikipedia)
  • MoinMoin
  • Wikispaces
  • ...
  • TWiki
  • Foswiki

See: WikiMatrix.

Slide 9: TWiki Facts

  • Created by Peter Thoeny in 1998.

  • Open Source; developers around the world

  • Installed on many corporate intranets, often behind firewalls

(See: twiki.org and TWiki:Main.TWikiInstallation)

Slide 10: Foswiki Facts

  • Forked out of TWiki in Oct 2008

  • Open Source; developers around the world

  • foswiki.org

Slide 11: Terminology in this Presentation

From here on, we will refer to TWiki and Foswiki together as "Wiki".

Slide 12: Wiki Enterprise Features

  • Many built-in "Enterprise" features

  • Additional functionality available by installing "plugins"

  • Structured ("database application") capabilities

Slide 13: Ease of Use

"Wiki shorthand"
  • Simple
  • Makes content easy and fast to create/modify
  • No HTML to learn

Case sensitive

  • WebHome vs WebHOme vs Webhome vs webhome
  • TWiki is spelled TWiki

Need more power?

  • HTML works
  • CSS works
  • JavaScript works

Slide 14: Enterprise Features

Access control

  • Allow topic view
  • Allow topic change
  • Users
  • Groups

More than just content

  • Variables (functions) add shortcuts
    today's date, topic name, colored text

  • Plugins (extensions) extend functionality
    calendars, arithmetic, slide shows

  • Embedded Applications
    blog, team directory, project tracker

Slide 15: Revision History

  • Anyone can publish

  • Anyone can edit

  • Anyone can change my page?!

The ability for anyone to write on any page can be liberating. It can also be scary or intimidating.

For those who lean toward "scary", you'll be pleased to know that many wikis (including ours) are backed by version control (e.g. RCS). So, even if you think you broke something, you (or someone else) can usually fix it. If you want to know what changes were made (and by whom), there's revision history.

Slide 16: Structured Wiki

TWiki/Foswiki are structured wikis. Although there are hundreds of examples of wikis, there are only a few structured wikis.

  • "Database-like" manipulation of data stored in forms on pages.
  • Users can create small applications
    status boards, task lists, department directories, project tracking systems, blog applications, ...
  • No special programming language is required.

"Enterprise" features
  • Access control
  • Revision control
  • Webs (separate collaboration categories)
  • E-mail notification (subscribe to topic changes)

(See: TWiki:Codev.StructuredWiki and Wikipedia:Structured_wiki)

Slide 17: Webs and Topics

TWiki and Foswiki are aninstallable, distributed, wiki program.

Webs
  • A Wiki site (installation) is divided into webs.
    • Each web usually represents one area of collaboration (e.g. one department or large project).

Topics
  • Each web has hyperlinked topics, displayed as pages in your browser.
    • Webs are analogous to folders on your computer.
    • Topics are analogous to documents.

Slide 18: Webs and Topics

  • Each web has a "home" topic (named WebHome) and various administrative topics (e.g. WebChanges, WebTopicList).

  • All other topics are created (and modified) by you and your co-workers.

   http://cfcl.com/bin/view/Learn/Tut/WikiTraining
  • Learn is a web.
  • Tut is a subweb (acts just like a web).
  • WikiTraining is a topic.

Slide 19: Administrative Webs

A Wiki distribution includes several administrative webs. You should not store permanent project content in these webs.

  • Main - user home and configuration pages

  • TWiki or System - system documentation and configuration

  • Sandbox - temporary topics, for testing and experimentation

Slide 20: Project Webs

Many groups and projects have their own web. Some have more than one!

Your group controls your web - who has access to view or edit topics, how to name those topics, what they contain. You can also control the template used for every new topic and the sidebar of your web. You can customize many aspects of your web without affecting any other webs in the site.

Slide 21: Topics

You (and your group) control your topics - who has access to view or edit them and what they contain. Your group may have naming conventions or other standards for topics. Be sure that you understand what these are.

Note: People often create links from their Wiki home pages. If you're not careful, this will create pages in the Main (administrative and homes) web. Pages created in Main are more difficult for your co-workers to find and work with.

Best practice is to create project topics in the most appropriate web.

We'll get to creating and editing topics further along in this session.

Slide 22: Using the Wiki

  • Navigation

  • Managing Topics (View, Attach, History, More...)

  • Creating Topics

  • Editing Topics

  • Attachments

Slide 23: Navigation

  • Breadcrumbs

  • Left Side Bar

  • Personal Side Bar

Slide 24: Breadcrumbs

The breadcrumb string shows a topic's relationship to other topics (pages).

breadcrumbs.jpg

  • The first item in the breadcrumb list is the Wiki site name (CFCL Wiki).
  • The second item in the breadcrumb list is the web (Help).
  • The last item in the list is the name of the current topic (WikiEssentials).
  • The item just before the current topic is the topic's "__parent__".

Important: With the exception of the web, this is not a "real" hierarchy. The breadcrumb list merely provides context and eases navigation.

Note: A topic can have only one parent. Some pages have no parents; these "orphan" pages have a breadcrumb list that goes directly from web to topic.

Slide 25: Left Side Bar

The left side bar can be customized for your web. Conventionally, this area includes a search field (search topic name or body content), useful links, related webs, and a section you can customize as a personal side bar.

Slide 26: Q&A -- Can I Make The Side Bar "Go Away"?

Q: I think the sidebar takes up too much space. Can I make it go away?

A: Yes. This isn't recommended for normal work, simply because the side bar can coontain a lot of Very Useful Links. But if you want to, you can make it disappear.

Slide 27: Personal Side Bar

create_personal_sidebar.jpg Click the "create" link in the left sidebar to customize Wiki with your own personal navigation links. You'll be provided with a default personal LeftBar page which you can edit to taste.

Slide 28: Managing Topics

  • View

  • Attach

  • History

Slide 29: Viewing: What's On A Wiki Page?

The content of each Wiki topic page is surrounded by standardized "chrome", including a left sidebar, breadcrumbs, and navigational links.

The links at the topic and bottom of the page (e.g. Attach, Edit) all have keyboard shortcuts (Alt-first-letter in Windows; Ctl-first-letter in Mac OS X).

SamplePageView.jpg

Slide 30: Breadcrumbs

The breadcrumb string shows a topic's "parent" relationship to other topics (pages).

screenshot

Slide 31: Current Version Information

Near the breadcrumb list, you can see the current version information for this topic: the most recent modification date, revision number, and WikiName of the person who last made a change.

revinfo.jpg

If you click on the WikiName, it will open that person's Wiki home page.

Note: Remember that this is a wiki; anyone can edit any page. Just because you see someone's name at the top does not mean that they are the original author (unless this is revision r1). If you're contacting someone about the content of a topic, keep this in mind.,

Slide 32: Raw View (or, How Did They Do That?)

If you just want to take a peek at the underlying code for a Wiki page, use the Raw view link at the bottom of the page. This gives you "read-only" access to the page source.

Slide 33: History

If you want more information on the history of a topic - who changed it, when, and what changes they made - click History at the bottom of the page. You can also compare versions of a topic. Click More topic options.

Slide 34: More Topic Actions

Click More topic options (in the lower right of any Wiki topic). On the next page, you can change many things about the topic, including:

  • rename it
  • move it to another web
  • make a copy in this web
  • delete it (Trash)
  • change the "parent" topic (breadcrumbs)
  • view "child" topics
  • view past revisions
  • compare revisions
  • find backlinks

Slide 35: Parent Topic

Parent relationships form the basis for the breadcrumb list.

  • The breadcrumbs show "parent" relationships for the current topic.
  • The parent (grandparent, etc) links make it easier to navigate the web.
  • By default, the parent is the page from which you first linked to this one.
  • A page created without linking first is "orphaned".

Slide 36: Parent Topic

To (re)set the parent topic,
  • Click More topic actions
  • Scroll down to Set New Topic Parent
    • If your web contains many pages, you'll see a fill-in box.
    • Otherwise, you'll see a menu of topics.

Setting the topic parent

See: WikiTutParentTopic

Slide 37: Attachments

Current attachments may be shown in a table at the bottom of the page.

Attachments at bottom of page

If you don't see this table, either:
  1. There are no attachments.
  2. or The "twisty" is closed (click toggleopen Show Attachments).
  3. or All attachments are "hidden" (Click Attach).

Click Attach to
  • upload a new attachment to a page
  • manage attachments that are already present

Hint: Think of "Attach" as short for "Attachments" (noun, not verb).

Slide 38: Attach a File

To attach a new file

  • Click Attach to reach the Attachments page.

  • On the next page, you'll see a form and a table of all current attachments.

AttachTo.jpg

Slide 39: Attach a File

  • Browse for the file.

  • Add an (optional) comment.

  • Set the properties of the atttachment (optional).

screenshot - checkboxes

  • If you're attaching an image you want to display:
    • Check Create a link to the attached file.
    • An <img link (HTML) will be appended to the body of your topic content. e.g.
   <img src="%ATTACHURLPATH%/attach1.jpg" alt="Attach " width='172' height='65' />
Move this link to the desired location and edit to taste.

  • If you prefer not to show the attachment when viewing the topic
    • Check Do not show attachment in table.

  • Click Upload file.

Slide 40: Managing Attachments

All attachments are listed on the Attachments page (even if they are hidden on the topic "view" page). If the attachment you want to manage is hidden, click the Attach button to reach the Attachments page.

screenshot -

To make changes to an attachment, click the manage link in the "Action" column of the table.

Slide 41: Managing Attachments

After a file is attached to a topic, you can:
  • update it (upload a new version)
  • change its properties
  • change the comment
  • delete it
  • change whether it's shown in the table
  • retrieve past versions
  • view its revision history

Slide 42: Managing Attachments - Update...

attachment_update.jpg

Slide 43: Creating Topics

To create a new topic, just give it a name.

Method 1: Make a link in any existing topic ‡

  • Edit any topic (preferably a related topic!)
  • Add a link to the new topic's name
  • Save

Wiki highlights the name to show that it is a potential link. (We'll discuss links in a few slides.) MyWidgets

  • Click the ?

  • Wiki will open an Edit window for the new topic

Note: The "parent" will be set to the topic that you linked from.

‡ We'll discuss links in more detail in a few slides

Slide 45: Creating Topics - Demo

Run Demo

Slide 46: Creating Topics - Type a URL

Method 2:

  • Type the URL to the (nonexistent) topic into the Address field of your browser.
  • When you press Return, Wiki will tell you that the topic doesn't exist.
  • Click "Create".

Note: Topics created in this way will be "orphans". You should set a parent topic using More topic options.

Slide 47: Creating Topics - Use a Form

If you're using a Wiki application, you may be provided with a form that makes it easy to add new topics.

hand Demo

Slide 48: Naming Topics

Choose topic names that are meaningful and unlikely to clash with the requirements of someone else in your group, now or in the future.

If I name a page MeetingNotes, can you guess whose meeting it covers? Which project? Can someone else guess?

Be clear and specific, even if the name seems long. For example, KumquatProjectMeetingNotes2008Q2.

Slide 49: A Web is a Shared Namespace

In computing terminology, a namespace is "an abstract container providing context for the items ... it holds". As a rule, names in a namespace cannot have more than one meaning; two or more things in the same namespace cannot share the same name.

A Wiki web is a shared namespace. Think of a folder on your computer. Two documents in that folder cannot have the same name. In the same way, two topics in the same web cannot have the same name.

Although Wiki only cares about exact matches, humans can be confused by very similar (or ambiguous) names. Choose names that will make sense to everyone using the web.

Slide 50: But... What About Breadcrumbs?

screenshot

Q: Don't the "breadcrumbs" show a hierarchy of pages? If my page is "under" Kumquat, isn't that good enough? Why do I have to also put KumquatProject in the name of the topic?

A: Unfortunately, breadcrumbs aren't "real". They provide a handy navigational aid and a convenient way to look at page relationships. However, they're not part of the namespace.

Just keep thinking of a web as a folder.
      One web - One folder - Many pages
      All jumbled together with no "real" organization.

It's up to you to help provide some virtual organization by sticking to a good naming convention.

Slide 51: Naming Topics

When creating new topics:

  • Use care in choosing a name.
    • Remember the shared namespace.
    • Keep naming conventions in mind.

  • Follow WikiWord syntax. A WikiWord consists of two or more words with initial capitals, run together.

  • Always begin topic names with a capital letter.

  • Use two or more words, or acronyms and words, in CamelCase.

  • Avoid using a single English word as a page name! For example Availability, Hosts, Monitoring, and Misc are all inappropriately vague names (which have been tried!).

  • Likewise, avoid using a single tool name or acronym as a page name.

  • Do not include the word "Wiki" in the name. (It's redundant unless the topic pertains to everything Wiki).

  • Avoid including the words "Web", "Topic", "Template" or "Form". Although these are not (strictly) reserved words, they have conventional meanings to Wiki.

Slide 52: Naming Conventions

If your web has a naming convention, stick to it.

(If you don't have a naming convention, this would be a good time to create one!)

If your page fits in an existing category of pages, please make that clear by including the relevant keyword, prefix- and/or -suffix when naming the page.

Type of Page Prefix Suffix Examples Notes
Customer related Customer   CustomerEntrance, CustomerNews "externally" facing pages
Focus Areas OnCall, Triage, Release...   OncallMasterHomePage, TriagePolicy, ReleaseCalendar Choose a prefix that clearly identifies the audience and type of content
Management related Mgmt   MgmtPortal, MgmtHeadcount Management areas,
not necessarily for use only by managers
may require Group privileges
Personal pages Personal     Personal pages are acceptable here.
Prefix topic name with Personal and be sure to
include your ID or name, e.g. PersonalVbrown, or PersonalVicki
Project related (general) Project   ProjectPortal, ProjectTracking  
Property or Subsystem related (specific) name of Property / Subsystem   FinanceBCP, SportsOps, FeedsOps standardized format
Team related Team   TeamPortal, TeamDirectory may require Group privileges





Portal (Entry) Page   Portal TeamPortal, ProjectPortal lots of links
BCP Procedures   BCP FinanceBCP  
FAQ   FAQ YMGParanoidsFAQ See the DocsFAQ index
Guidelines   Guideline(s) MeetingGuidelines, EmailGuidelines See the DocsProcedures index
How to... HowTo   HowToCloneNewServer See the DocsHowTo index
Index   Index ProjectArchReviewIndex usually uses a Search to produce an index
requires adherence to naming conventions
Open Issues tracking   OpenIssues PlatformOpenIssues, OpenIssues  
Policies   Policy EngrResponsePolicy See the DocsPolicy index
Procedures   Procedure(s) FinanceOncallProcedures See the DocsProcedures index
Processes   Process HRCSubmissionProcess  
Tools   Tools ToolsResource See the DocsTools index

Slide 53: Administrative (Restricted) Keywords

If you aren't completely confident of how these work, do not use these keywords in topic names!

Type of Page Prefix Suffix Examples Notes
Doc portals Docs   DocsGuidelines, DocsCustomer See the DocumentationLibrary index
Web admin Web   WebAttic, WebChanges  
Template   Template WebTopicEditTemplate Copy/paste or used by Wiki
See the DocsTemplates index; use this suffix with care
Template
strict creation mechanism
  TemplateStrict TriageMapTemplateStrict, ProjectDetailTemplateStrict Used via Form
Do not try to manually copy from these!

See: TopicGuidelines

Slide 54: Editing Topics - Add or Change Content

Use the Edit link (in the upper right or lower left of any Wiki page) to open that page to make changes.

Slide 55: Q&A - What about the WYSIWYG Editor?

Q: I see a WYSIWYG button. Can I use that?

A: You will have more control with the regular editor, because you will be able to see exactly what you're doing. Also, some of the features of the WYSIWYG editor may not work with all browsers.

Finally, the WYSIWYG editor may not work as well on pages that contain more than the simplest Wiki markup. In particular, the WYSIWYG editor has been reported to break tables.

If the page contains more than very simple text, exercise caution or use the regular editor.

Slide 56: Who is Editing This Page?

When you click the Edit link, Wiki starts a 60-minute "timer" for you. This 60-minute timer is used for version history as well as for notifying others that you have the page open for editing.

To avoid setting the timer (if you just want to look at a page), be sure to use Raw View.

When you save the page after making changes, Wiki will "sign it" with your name and the current date and time (in GMT). This information appears in the upper right corner of each page.

Slide 57: Q&A -- What if Someone Else is Editing?

Q: What happens if two people edit a page at the same time?

A:Wiki will notify you if you try to edit a page that someone else has open for editing. You can choose to wait, to edit anyway, or to contact the other person and arrange a mutually convenient time to edit.

If you choose to make your changes anyway, Wiki will try to merge both sets of changes together. It usually does this correctly; however, you should always review the page carefully to be sure no mistakes were made.

Slide 58: Edit: What's On The Page?

screenshot - Anatomy of an edit

Slide 59: Formatting Help

Every Edit page has Formatting help at the top of the page. If you don't see the formatting help section, click the Show Help link just above the editing area.

FormattingHelp.jpg

Slide 60: Fixed Width Font

A fixed-width (monospace) font is recommended for editing bullet lists and other places where spaces really matter.

Look at the bottom right of the page below the Edit area. Click the Courier i to set the edit area to fixed-width font.

screenshot

Slide 61: Preview, Checkpoint, Save, (or Cancel)

You can preview your page before saving, then go back and fix anything you don't like. Just click the Preview button at the bottom left of the Wiki edit screen.

If you're making a lot of edits and don't want to keep saving and then clicking Edit again, use the "Checkpoint" button.

screenshot

Note: Some things, such as links and extensions, will not be fully functional in Preview mode. Preview is for quick reviewing, not complete testing.

Slide 62: Preview, Checkpoint, Save, (or Cancel)

screenshot

  • Preview - Review changes without saving yet.
  • Checkpoint - Save and continue editing. (Resets screen to top.)
  • Save - Save and exit Edit mode. Return to View mode.
  • Cancel - Discard any changes you have made. eRturn to View mode.

The buttons have keyboard shortcuts (Alt-first-letter in Windows; Ctl-first-letter in Mac OS X).

Note:
  • "Quiet Save" is just like Save, but does not schedule notifications of changes. You should usually just use "Save".
  • Preview mode may be incomplete (e.g. links aren't clickable, some things won't run...)
  • Checkpoint saves the file on disk but does not (necessarily) change the revision history.

Slide 63: Force New Revision

screenshot

Normally, if you make multiple edits within a one hour period, Wiki will fold your changes together and make one backup in the revision history. This is often the "right thing to do", as it reduces the visual clutter of many updates.

The "Force New Revision" checkbox is a way to force Wiki to create a separate revision when you Save (or Checkpoint).

Slide 64: Q&A - What if I change my mind?

Q: What if I change my mind?

A: If you decide to leave an "Edit" session without making any changes, be sure to click Cancel (at the bottom of the page) When you click Cancel, the 60-minute timer is reset.

Otherwise, (e.g. if you click the Back button), Wiki keeps the timer running. Anyone else who tries to edit the page will receive a notice that you still have the page open for editing!

Slide 65: Wiki Shorthand

Working in Wiki is as easy as typing in text - much like using email. You don't need to know HTML to create a web page in minutes. Wiki shorthand gives you much of the power of HTML with a simple coding system that takes little time to learn.

Every edit page has a "Formatting help" section at the top with examples of Wiki shorthand. The link in the last entry, More formatting help, will pop up a page with even more examples.

Slide 66: Q&A: Can I Use HTML?

Q: I already know HTML. How bad is it if I use HTML instead of Wiki shorthand?

A: Wiki supports all HTML, so you can use HTML if you want to.

CanUseHTML.jpg However, the general recommendation is to use Wiki shorthand whenever you can. This makes things easier for anyone else who may edit the page and keeps the text uncluttered and easy to edit. In many cases, Wiki syntax is a lot simpler and smaller than the equivalent HTML code.

Slide 67: Using HTML

Recommendation:

  • Use Wiki shorthand most of the time (simplicity).

  • Use HTML when Wiki shorthand isn't up to the task (power).

Note: There are a few caveats for using HTML. Be sure to read UsingHTML.

By default, Wiki will try to create a link for any WikiWord. That's all you need. However, many people prefer more control than this.

Some terms just look like WikiWords. Do you always want to link these?
  • MySQL
  • MediaWiki
  • FreeBSD

Even if you do want a link, do you want a link everywhere that term appears on the page?

Slide 69: Prevent Automatic Linking

Use <nop> or ! to prevent attempts to automatically link a single WikiWord.

  • !FreeBSD
  • <nop>FreeBSD

Slide 70: Prevent Automatic Linking

To prevent automatic linking for all (or part) of a page, wrap the content in <noautolink> tags:

  <noautolink>
     
     _Content_

  </noautolink>

You're in control.

To force linking, use [[...]].

  • [[MyWidgets]] - A link to a topic in the current web

  • [[My Widgets]] - You can add spaces for clarity. (Wiki will ignore spaces inside the [[ ]], but you'll see them.)

  • [[Home.MyWidgets]] - A link to a topic in the Home web

Note: I prefer to use [[ ]] everywhere, even if the page doesn't use <noautolink>, because it is more flexible and makes the links more obvious in the source.

  • [[MyWidgets][View my widgets page]] - Change the text for the link.

  • http://apple.com - Full HTTP URLs turn into links automatically; there's no need to include the <a href part.

  • [[http://apple.com][Apple]] - Change the text for the link (no need to include the <a href).

Use Wiki shorthand (not full URLs) for links to pages within the Wiki.
  • Links will be shorter.
  • Raw pages will be easier to read and edit.
  • Wiki "knows" the path up to the name of the web.
  • Wiki shorthand will help if you ever decide to rename a page (Wiki can find these links and update them for you).
  • Links will continue to work if pages are copied or moved to another server.

If you like to be specific, you can include the Web portion.
  • [[Home.MyWidgets]] -- a link to a topic in the Home web
    (always works, even if the page containing this link is in the Home web).

Use spaces to make links more readable:
   [[Wiki Tut Training]]
WikiTutTraining

When changing the link text that will be shown on the screen, here's a useful mnemonic:

  • The Link goes on the Left.

  • The Rest goes on the Right.

Remember that the brackets need to match [[ ... ][ ... ]].

Slide 76: Wiki shorthand - Examples

  • Separate adjacent paragraphs with one or more blank lines.

  • Bold text - wrap text in asterisks: *your words*.

  • Italic text - wrap text in underscores: _your words_.
    Double for bold italic: __your words__.

  • Monospaced text - wrap text in equal signs: =your words=.
    Double for bold mono: ==your words==.

Slide 77: Headings

Headings: At the beginning of the line: 3 dashes, 1 to 6 plusses, 1 space.
---++ Your Heading

The number of plusses matches the level of the heading. Different levels have different styling.

Recommendation: Use a single level-1 heading for the page title, then use level 2 and lower for subsequent headings.

Slide 78: Headings

---+ Level 1 Header
---++ Level 2
---+++ Level 3
---++++ Level 4
---+++++ Level 5
---++++++ Level 6

screenshot

Slide 79: Table of Contents

A Wiki Table of Contents (TOC) is created from the headings on a page.

To prevent a given header from showing in the Table of Contents, add !! after the last +.
---+!! Level 1 Header (not in TOC)
---++!! Level 2 (not in TOC)

Hint: I usually hide the level-1 header from the TOC. There's only one and it's above the TOC anyway.

Note: If you skip a level (e.g. go from level 2 to level 4), the TOC will look odd.

Slide 80: Bullets

Bullet list: 3 spaces, asterisk, 1 space. To add another level of indentation, add three more spaces at the beginning of the line.

   * Bullet list
      * indentation level 2
         * indentation level 3
      * indentation level 2

  • Bullet list
    • indentation level 2
      • indentation level 3
    • indentation level 2

Note: When Wiki says "3 spaces" it means 3 spaces (or a multiple of 3). Not 2. Not 4. This is one of the most common goofs people make using Wiki.

Slide 81: Ordered Lists

Ordered list: 3 spaces, 1., 1 space. To add another level of indentation, add three more spaces at the beginning of the line.

Example:

   1. First
      1. indentation level 2
         1. indentation level 3
   1. Second
   1. Third

Results:

  1. First
    1. indentation level 2
      1. indentation level 3
  2. Second
  3. Third

Note: Use can use 1 or 1. (the . isn't required.)

Slide 82: Tables (Simple)

  • Each table cell starts and ends with a vertical bar |.
  • Build a table by repeating rows of cells.
    • No blank lines between rows!

  • | *Bold Cells* | are displayed as "header" cells (HTML <th>)
    • "Header" cells do not need to be in the first row.

  • Extra white space in cells (more than 1 space) justifies contents: left, right, or centered.
    • left is the default

Slide 83: Tables

| *Header* | *Header* | normal |
|    right |   center   | left    |
| *header* | normal | <b>just bold</b> |
| normal | normal | normal |


Header Header Normal
right center left
header normal just bold
normal normal normal

Slide 84: Horizontal Rules

A series of at least three dashes at the beginning of a line

--------

causes a page-wide horizontal rule to be displayed.


Note: If you need customization, use HTML <hr>.

<hr width=400>


Slide 85: Verbatim Text

Wiki does not change verbatim text. The result looks just like the source (as if you clicked "Raw View" on the page.)

Many of the examples in this presentation are formatted using <verbatim>.

  <verbatim>
  ---++ Wiki Markup (Formatting Help)

  Every Edit page has *Formatting Help*.

     * *bold text* - wrap in asterisks

  </verbatim>

Slide 86: Editing Pages - Q&A

Q: I have a document in MS Word (or Excel). How difficult is it to convert this to Wiki?

A: If you use Windows, there are macros available to ease the export of Word or Excel files into Wiki format. On Mac OS X or *nix, things get a bit more complicated.

Hint: If you've been in the habit of using Word as a scratch pad for new documents, you might want to change your habits. It should be easier (and faster!) to create a document in Wiki initially than to create it first in Word and then convert it.

Slide 87: Q&A - Help! I messed it all up.

Q: What if I mess everything up and break the page?

A: Wiki saves version history for every person who changes a page. For convenience, all changes you make (and save) during one 60 minute period will be folded into one saved revision.

If you "mess up" a page, you can usually retrieve the previous version. You can view all past versions (yours and everyone else's) using the appropriate links at the bottom of the "view" page.

Slide 88: Content (or, Aack! I have to Write Something!)

A lot of people hate writing documentation. They don't mind writing, but they can't stand the thought of Writing.

So... don't.

Don't think too much about formatting. Don't think about word choice or commas or spelling or grammar or Aaaaargh!

Don't think. Just type. Get the thoughts down in electrons. We'll make it all pretty later.

Slide 89: Content Guidelines

When you are ready to think about format:

  • Keep It Short and Simple
  • Write Conversationally
  • Think Globally
  • Divide and Conquer
  • Break it Up
  • Highlight Key Words
  • Set off Commands
  • Choose Good Role Models
  • Request a Review
  • Practice

See: ContentGuidelines for detailed recommendations.

Slide 90: Appendix: Managing Topics

Some Tips and Best Practices for managing the topics in your web:

  • Improve navigation with reasonable parent topic relationships.

  • Periodically review and prune old pages, deprecating or removing stale content.

Slide 91: Appendix: Personal Customizations

You can customize parts of your Wiki experience.

Slide 92: Your Home Page

Every Wiki user has a personal Home page in the Main web. You can customize this page with your contact information, notes, sample bits of Wiki code... whatever you like.

Your home page is probably at Main/FirstnameLastname. e.g. Main/VickiBrown.

Note: There is a variable you can use to see your Wiki Name: %WIKINAME%. (You are WikiGuest).

Slide 93: Notification

Wiki can send you email to notify you of changes to one topic, several topics, or all topics in a web.

Edit the WebNotify topic in the web you're interested in. Follow the instructions and add a bullet with your Wiki name or email address.

Notification frequency is configured by your Wiki administrator.

Slide 94: Editing Enhancements

It can be frustrating to type text into a browser window. Remember that you have more control than you think.

Hint: Use Firefox.
  1. "Check spelling as you type" for text areas.
  2. Extensions allow you to use an external editor of your choice to edit the contents of textareas. Try It's All Text.

Slide 95: What's Next?

Topic editing in Wiki is similar to what you'd find in most wikis. Where TWiki differs is in its use of variables, plugins, and structured data.

Learn More:

Slide 96: References - "Official"

The following are part of the Wiki distribution:

Slide 97: Getting Help

Talk to your co-workers. It's always OK to ask for help and share ideas.

Visit http://twiki.org or http://foswiki.org

Join the IRC conversation at #twiki at irc.freenode.net.

Topic revision: r7 - 02 Jan 2016, VickiBrown
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback