Webs and Topics
Slide 1: Essential Wiki - Webs & Topics
Slide 2: What's Covered
- What's a Wiki?
- What's TWiki / Foswiki?
- Webs and Topics
- Working With Topics
- More Topic Actions
- 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?
- 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
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
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
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.
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
are just two available wikis.
- MediaWiki (used by Wikipedia)
Slide 9: TWiki Facts
- Created by Peter Thoeny in 1998.
- Open Source; developers around the world
- Installed on many corporate intranets, often behind firewalls
Slide 10: Foswiki Facts
- Forked out of TWiki in Oct 2008
- Open Source; developers around the world
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
- Makes content easy and fast to create/modify
- No HTML to learn
- WebHome vs WebHOme vs Webhome vs webhome
- TWiki is spelled
Need more power?
- HTML works
- CSS works
Slide 14: Enterprise Features
- Allow topic view
- Allow topic change
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 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
- "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.
- Access control
- Revision control
- Webs (separate collaboration categories)
- E-mail notification (subscribe to topic changes)
Slide 17: Webs and Topics
are aninstallable, distributed, wiki program.
- A Wiki site (installation) is divided into webs.
- Each web usually represents one area of collaboration (e.g. one department or large project).
- 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.
- All other topics are created (and modified) by you and your co-workers.
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.
: 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
- Managing Topics (View, Attach, History, More...)
Slide 23: Navigation
Slide 24: Breadcrumbs
The breadcrumb string shows a topic's relationship to other topics (pages).
- 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__".
: With the exception of the web
, this is not a "real" hierarchy. The breadcrumb list merely provides context and eases navigation.
: 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"?
: I think the sidebar takes up too much space. Can I make it go away?
: 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
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
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).
Slide 30: Breadcrumbs
The breadcrumb string shows a topic's "parent" relationship to other topics (pages).
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.
If you click on the WikiName, it will open that person's Wiki home page.
: 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.
Slide 37: Attachments
Current attachments may be shown in a table at the bottom of the page.
If you don't see this table, either:
- There are no attachments.
- or The "twisty" is closed (click Show Attachments).
- or All attachments are "hidden" (Click
- 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
Attach to reach the Attachments page.
- On the next page, you'll see a form and a table of all current attachments.
Slide 39: Attach a File
- Add an (optional) comment.
- Set the properties of the atttachment (optional).
- If you're attaching an image you want to display:
- Check Create a link to the attached file.
<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.
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.
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...
Slide 43: Creating Topics
To create a new topic, just give it a name.
Slide 44: Creating Topics - Make a link
: Make a link in any existing topic ‡
- Edit any topic (preferably a related topic!)
- Add a link to the new topic's name
Wiki highlights the name to show that it is a potential link. (We'll discuss links in a few slides.)
- Wiki will open an Edit window for the new topic
: 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
Slide 46: Creating Topics - Type a URL
- 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".
: 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.
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
, 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,
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?
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
in the name of the topic?
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
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
| Customer related
|| 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
|| MgmtPortal, MgmtHeadcount
|| Management areas,
not necessarily for use only by managers
may require Group privileges
| Personal pages
|| 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)
|| ProjectPortal, ProjectTracking
| Property or Subsystem related (specific)
|| name of Property / Subsystem
|| FinanceBCP, SportsOps, FeedsOps
|| standardized format
| Team related
|| TeamPortal, TeamDirectory
|| may require Group privileges
| Portal (Entry) Page
|| TeamPortal, ProjectPortal
|| lots of links
| BCP Procedures
|| See the DocsFAQ index
|| MeetingGuidelines, EmailGuidelines
|| See the DocsProcedures index
| How to...
|| See the DocsHowTo index
|| usually uses a Search to produce an index
requires adherence to naming conventions
| Open Issues tracking
|| PlatformOpenIssues, OpenIssues
|| See the DocsPolicy index
|| See the DocsProcedures index
|| 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
| Web admin
|| WebAttic, WebChanges
|| Copy/paste or used by Wiki
See the DocsTemplates index; use this suffix with care
| Doc portals
|| DocsGuidelines, DocsCustomer
|| See the DocumentationLibrary index
strict creation mechanism
|| TriageMapTemplateStrict, ProjectDetailTemplateStrict
|| Used via Form
Do not try to manually copy from these!
Slide 54: Editing Topics - Add or Change Content
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?
: I see a WYSIWYG button. Can I use that?
: 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?
: What happens if two people edit a page at the same time?
: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?
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.
Slide 60: Fixed Width Font
A fixed-width (
) 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
to set the edit area to fixed-width font.
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.
: 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)
- 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).
- "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
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?
: What if I change my mind?
: 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?
I already know HTML. How bad is it if I use HTML instead of Wiki shorthand?
Wiki supports all HTML, so you can use HTML if you want to.
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
- Use Wiki shorthand most of the time (simplicity).
- Use HTML when Wiki shorthand isn't up to the task (power).
: There are a few caveats for using HTML. Be sure to read UsingHTML
Slide 68: Making Links
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?
Even if you do want a link, do you want a link everywhere
that term appears on the page?
Slide 69: Prevent Automatic Linking
to prevent attempts to automatically link a single WikiWord.
Slide 70: Prevent Automatic Linking
To prevent automatic linking for all (or part) of a page, wrap the content in
You're in control.
Slide 71: Tell TWiki Where to Make a Link
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
: I prefer to use
everywhere, even if the page doesn't use
, because it is more flexible and makes the links more obvious in the source.
Slide 72: Use Double Brackets for Links
[[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
Slide 73: Link Guidelines
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.
Slide 74: Link Guidelines
If you like to be specific, you can include the
[[Home.MyWidgets]] -- a link to a topic in the
(always works, even if the page containing this link is in the Home web).
Use spaces to make links more readable:
[[Wiki Tut Training]]
Slide 75: Tip: Links
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:
- Italic text - wrap text in underscores:
Double for bold italic:
Monospaced text - wrap text in equal signs:
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
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.
: 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 2
: 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 space. To add another level of indentation, add three more spaces at the beginning of the line.
1. indentation level 2
1. indentation level 3
- indentation level 2
- indentation level 3
: Use can use
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
- "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.
Slide 83: Tables
| *Header* | *Header* | normal |
| right | center | left |
| *header* | normal | <b>just bold</b> |
| normal | normal | normal |
|| just bold
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.
: If you need customization, use HTML
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
---++ Wiki Markup (Formatting Help)
Every Edit page has *Formatting Help*.
* *bold text* - wrap in asterisks
Slide 86: Editing Pages - Q&A
: I have a document in MS Word (or Excel). How difficult is it to convert this to Wiki?
: 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.
: 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.
: What if I mess everything up and break the page?
: 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
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
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
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
: There is a variable you can use to see your Wiki Name:
. (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.
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.
- "Check spelling as you type" for text areas.
- 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.
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.
Join the IRC conversation at