20-Minute TWiki Tutorial

This step-by-step, hands-on tutorial gets you up to speed with all the TWikiSite basics, in mere minutes...

1. Get set...

Open two browser windows, so that you can follow these steps in one window, while trying things out in the other.

2. Take a quick tour...

A TWikiSite is divided into webs; each one usually represents one area of collaboration. You can navigate the webs from each web page; by default, those links are located either in the lower part of the menu on the left hand side or near the upper right corner.

• Each web has hyperlinked topics, displayed as pages in your browser.
• The home page in each web is the WebHome topic.
• To browse a TWiki web, just click on any highlighted link. These links are called WikiWords and comprise two or more words with initial capitals, run together.
• Follow the WikiWord link and learn what it is.
• If you know the name of a topic, you can jump directly to it by typing its name into the Jump field on the top of the page. Type WebSearch to jump to the search page.
  Do not confuse the Jump field with the Search field.
• You can search each TWiki web. Enter a search string in the WebHome topic or the WebSearch topic accessible from the Search field on each topic. TWiki searches for an exact match; optionally, you can also use RegularExpressions.

3. Open a private account...

To edit topics, you need to have a TWiki account.

• Go to the TWikiRegistration page to create your TWiki account. Fill in a couple of lines and you're set!

4. Check out TWiki users, groups.

• Go to the TWikiUsers topic in the TWiki.Main web; it has a list of all users of TWiki. Your WikiName will be listed after you register.
• Go to the TWikiGroups topic in the Main web; it has a list of groups which can be used to define fine grained TWikiAccessControl in TWiki.

5. Test the page controls...

The color-coded control strips at the top and/or bottom of the page have a collection of action links. Different skins show different links, but most will have some or all of:

• Edit - add to or edit the topic (discussed later) using an editor that resembles a normal text editor
• Attach - attach files to a topic (discussed later)
• Print version - goes to a stripped down version of the page, good for printing
• History - topics are under revision control - History shows you the complete change history of the topic, for example, who changed what and when
• r3 > r2 > r1 - view a previous version of the topic or the difference between two versions
• Backlinks - find out what other topics link to this topic (reverse link)
• Raw View - show the source text without editing the topic
• Raw Edit - add to or edit the source text of the topic (discussed later), using TWikiShorthand
• More topic actions - additional controls, such as rename/move, version control and setting the topic's parent.

6. Change a page, and create a new one...

6.1 ... using the WYSIWYG-Editor (easiest for new users)

Go to the Sandbox. This is the sandbox web, where you can make changes and try it all out at will.

• Click the [Edit] link. You are now in edit mode. (Go to a different topic like TWikiGuestSandbox if you see a "Topic is being edited by an other user" warning.)
• Although the edit page and the rendered page are quite similar, compare both versions with each other (move back and forth in your browser).
• Notice how WikiWords are linked automatically; there is no link if you look at the text in edit mode.
• Now, create a new topic - your own test page:
  1. In edit mode, enter a new text with a WikiWord, for example:
     This is TWikiGuestSandbox topic.
  2. Save the topic. The name appears, underlined, with a linked question mark at the end. This means that the topic doesn't exist yet.
  3. Click on the question mark. Now you're in edit mode of the new topic.
  4. Type some text, basically, like you write an e-mail.
  5. A signature with your name is already entered by default.
     The Main. in front of your name means that you have a link from the current web to your personal topic located in the Main web.
  6. Save the topic...
• Learn about text formatting. You can enter and format text as if using a normal text editor. Just highlight the words or phrases you want to modify and change its format using the toolbar in the upper part of the edit window. Most icons are self explaining or you might already know them. And if you do not know an icon, just try it to see what happens!
  1. Go back to your sandbox topic and edit it. For example, type a new header.
  2. Highlight the new text and change the it from Normal to Heading 3.
     If you need help, click on the Edit help link located above the text box in edit mode.
  3. Save the topic.

6.2 ... manipulating the text source (strongly recommended for more experienced users)

Go to the topic you were just editing in the Sandbox.

• Click the Raw Edit link. You are now in edit mode and you can see the text source of the topic. (Go to a different topic like TWikiGuestSandbox if you see a "Topic is being edited by an other user" warning.)
• Look at the text in edit mode and compare it with the rendered page (move back and forth in your browser).
• When you only want to see the source code of a topic click the Raw View link.
• Notice how WikiWords are linked automatically; there is no link if you look at the text in edit mode.
• Now, create a new topic - your own test page:
  1. In edit mode, enter a new text with a WikiWord, for example:
     This is TWikiGuestRawView topic.
  2. Preview and save the topic. The name appears, underlined, with a linked question mark at the end. This means that the topic doesn't exist yet.
  3. Click on the question mark. Now you're back in the WYSIWYG edit mode of the new topic. Just save the topic and use the Raw Edit link of the new topic to get into the text source again.
  4. Type some text, basically, like you write an e-mail.
  5. Preview and save the topic...
• Learn about text formatting. You can enter text in TWikiShorthand, a very simple markup language. Follow the TWikiShorthand link to see how, then:
  1. Go back to your sandbox topic end edit it.
  2. Enter some text in TWikiShorthand: bold text, italic text, bold italic text, a bullet list, tables, paragraphs, etc.
     If you need help, click on the Edit help link located above the text box in edit mode.
  3. Preview and save the topic.

7. Use your browser to upload files as page attachments...

You can attach any type of file to a topic - documents, images, programs, whatever - where they can be opened, viewed, or downloaded.

• Attaching files is just like including a file with an e-mail.
  1. Go back to your sandbox topic and click on the [Attach] link at the bottom.
  2. Click [Browse] to find a file on your PC that you'd like to attach; enter an optional comment; leave everything else unchecked.
  3. Click [Upload file], then scroll to the end of the page to see the new attachment listing.
• Do this again - this time, upload a GIF, JPG or PNG image file.
  • Check the Properties: box saying Create a link to the attached file. Once saving the topic, the image will show up at the bottom of the topic.
  • To move the image, edit the topic and place the last line (containing %ATTACHURL%) anywhere on the page.
• If you have a GIF, JPG or PNG image of yourself, your cat, your sprawling family estate...why not upload it now to personalize your account page TWikiGuest?

8. Get e-mail alerts whenever pages are changed...

WebNotify is a subscription service that automatically notifies you by e-mail when topics change in a TWiki web. This is a convenience service - for many people, checking e-mail is easier than checking the Web.

• If you're using TWiki to collaborate on a project, it's important to know when anyone on your team posts an update. If you're following a specific discussion, it's convenient to know when there's new input.
• Alerts are e-mailed as links to individual topics that've been changed in a set period: each day, every hour, whatever is configured for your system.
• It's strongly recommended that you try out the service by subscribing to each TWiki web that's relevant to you. You can subscribe and unsubscribe instantly, on a per web basis using WebNotify.

That's it! You're now equipped with all the TWiki essentials. You are ready to roll.

When first using TWiki, it will probably seem strange to be able to change other people's postings - we're used to separating individual messages, with e-mail, message boards, non-Wiki collaboration platforms. Don't worry about it. You can't accidentally delete important stuff - you can always check previous versions, and restore them, if necessary, if you want to undo any changes. After a short while, TWiki-style free-form communication becomes second-nature. You'll expect it everywhere!

Related Topics: UserDocumentationCategory

---

Comments & Questions about this Distribution Document Topic

The TWikiUsers topic in the TWiki.Main web looks very empty to me, even after I have registered myself...

Actually, I was first looking for instructions pertaining to the local installation of the beta TWiki to my own machine, instructed by the readme file to look for a TWikiDocumentation and wanting to compare the version I had locally with the last one from the org site

-- MarcGirod - 02 Apr 2005

The TWikiUsers topic is now fixed.

-- PeterThoeny - 04 Apr 2005

Still seems like it doesn't hold your hand enough for non-HTML/programmer types, the users I'm looking at would need a WYSIWYG 'Word'-ish interface.

Still, better than Drupal, and it's Perl CGI (not mod_perl like Slash!)

-- SimonJohn - 17 Aug 2005

TWiki 4.2 has a relatively solid WYSIWYG editor.

-- PeterThoeny - 04 Jul 2008

Point (2) talks about the Webs being in the "top right" part of the page, but that is not where they are located in the default skin. Perhaps this should be made location neutral, like "toward the top of each page" or maybe just give examples of how it looks in Pattern skin.

Also, I think now that the WYSIWYG editor comes standard in TWiki 4.2, this document needs a pretty substantial overhaul. If I send a link to this tutorial on our wiki to some of our less technical coworkers, they are going to get confused when it starts talking about editing pages, and what toolbar buttons / commands are present on every page for toolbar. Either that, or revert to having an "Edit" button and a "WYSIWYG" button. That might confuse new, non-technical users as well, but seems to be the outcry around TWiki:TWiki

-- AdamNofsinger - 08 Jul 2008

Good points, thanks Adam. Please feel free to help improve the documentation. Edit this page here.

-- PeterThoeny - 13 Jul 2008

I just updated this topic so that it fits more to the current TWiki stable. Any comments are welcome!

-- SebastianKlus - 30 Jul 2008