# <a name="GoodStyle Collaboration Tips"></a><a name="_GoodStyle Collaboration Tips"></a> GoodStyle Collaboration Tips
-- TWiki has very simple **[[text formatting rules|Main/TextFormattingRules]]**. You won't go wrong if you:
+- TWiki has a very simple **[[text formatting shorthand|Main/TWikiShorthand]]**. In any case, you won't go wrong if you simply:
- start each line without spaces
- separate paragraphs with a blank line
-- Run together capitalized words to make **[[WikiWords]]:**
+- Run together capitalized words to form **[[WikiWords]]:**
- [[WikiWords]] automatically appear as hyperlinks
- - make up meaningful Wiki names - it can be a challenge (it'll sharpen you up!)
+ - make up meaningful, reasonably brief Wiki names - it can be a challenge (it'll sharpen you up!)
- [[WikiWords]] has name-creation tips that may help
- If a **discussion** is going on:
- - separate each follow-up with a horizontal rule
+ - separate each follow-up with a space
- add your [[WikiName]] and the date at the end
- OR, by all means, insert your comment where it seems to fit best:
- you may want to inset it with a bullet and/or _set it in italics_ so it's clear (always sign and date)
+ - if a sub-topic develops, separate it with a horizontal rule at beginning and end
- A good format for a **new topic** is "dissertation followed by discussion":
- - start with a brief, factual introduction
- - then bring on the opinions.
+ - start with a brief, factual introduction, followed by double horizontal rules
+ - let the discussion begin
-- When a discussion dies down and the page becomes static, feel free to **refactor mercilessly**:
+- When a discussion dies down and the page becomes static, if you're clear on your course, feel free to **refactor mercilessly**:
- fearlessly edit down to capture the key points
- reduce the noise without losing the facts or the flavor
- - if you merge or delete comments, you can group credit `Contributors:` at the end of the page
- - That's how Wiki content matures and grows in value over time.
+ - if you merge or delete comments, group credit `Contributors:` at the end of the page
+ - _This is how Wiki content matures and grows in value over time._
- For **external site links**, you can type URLs directly into the text - `http://etcete.ra/...` - it'll clear to anyone where they're headed on click.
- TWiki is intended for world-wide use, and an international **standard date format** like 01 Sep 2001 is preferred. It's universally understood, and clearer than the xx/xx/xx format, where a date like 9/1/01 can mean either Jan or Sep, depending on the local conventions of the readers. For months, use the first three letters: Jan, Feb, Mar, Apr,...
-- Check the source when you want to find out how something is formatted: click <code>**Edit**</code> on the lower toolbar. To see earlier versions, click <code>**More**</code>, then check <code>**Raw text format**</code> and click <code>**View revision**</code>. A bit of HTML experience can't hurt, but you'll soon see with TWiki shorthand how far that is from necessary.
+- **TIP:** Check the source when you want to find out how something is formatted: click <code>**Edit**</code> on the lower toolbar. To see earlier versions, click <code>**More**</code>, then check <code>**Raw text format**</code> and click <code>**View revision**</code>. A bit of HTML experience can't hurt, but you'll soon see with [[TWikiShorthand]] how far that is from necessary.
--- [[PeterThoeny]] - 13 Sep 2001<br /> -- [[MikeMannix]] - 14 Sep 2001 <br />
+-- [[MikeMannix]] - 01 Dec 2001
Welcome Main.admin,
-You have reached a [[TWikiSite]] (pronounced twee-kee site). %WIKITOOLNAME% is a meeting place to collaborate on common interests. Everybody can contribute by just using a Web browser. It looks like a normal Web site, but then... everybody can (and is encouraged to) **edit the web pages** here and to contribute their questions and what they know. It really is very simple to learn and use.
+You have reached a [[TWikiSite]] (pronounced twee-kee site). TWiki is a meeting place where people collaborate on common interests. Anyone can contribute using a regular Web browser. TWiki looks like a normal Web site, but it allows (and ecourages) everyone to **edit the web pages** and contribute their questions and input. It really is very simple to learn and use, and provides possibly the most powerful way to exchange and develop ideas online, in an open, uncomplicated environment.
-**How %WIKITOOLNAME% Works**
+**How TWiki Works**
-1. **Read:** You can treat this web site like any other. Just read and follow interesting links.
- - **Web:** %WIKITOOLNAME% is divided up into webs; each one represents one area of collaboration. The webs are accessible at the upper right corner.
- - **Topic:** Each web has hyper-linked topics. A topic is one web page in your browser.
- - **What's New:** Visit [[WebChanges]] in any %WIKITOOLNAME% web to see what other people are doing here and what is currently being discussed.
-2. **Create an Account:** Before you'll be able to write new content on this site you'll need to create an account for yourself. Its simple, and only takes a minute. Just visit [[TWikiRegistration]] and fill out the form. This will also create your personal home page.
-3. **Write:** If you have something to say, you can and should (most of the time). Anyone can change or add to anything they see written in a %WIKITOOLNAME% topic. You can edit a topic from within your browser, using [[WikiSyntax]], a very simple markup language (you could also use HTML if you wish, but this is optional). To contribute,
+1. **Read:** You can treat this site like any other. Browse, and follow interesting links. A couple of hints:
+ - **web:** A [[TWikiSite]] is divided into webs; each one represents one subject, one area of collaboration. You can reach any web from the links in the upper right corner of every page.
+ - **topic:** Each web is made up of hyperlinked topics - [[TWikiPages]] that appear in your browser.
+ - **What's new:** Visit [[WebChanges]] in any TWiki web to see what other people are discussing and what's been added most recently.
+2. **Create an Account:** To be able to write new content on this site, you'll need to create an account for yourself. It's simple, and only takes a minute: just visit [[TWikiRegistration]] and fill out the form. This will also create your personal home page.
+3. **Write:** If you have something to say, speak your mind! Anyone can change or add to anything they see written in a TWiki topic. You can edit a topic from within your browser, using [[TWikiShorthand]], a very simple markup language (you can also use HTML if you like, but you'll usually find you can get the same results more easily with [[TWikiShorthand]]). To contribute,
- click the `Edit` link at the bottom of the page, edit the text, and then
- click the `[ Preview Changes ]` button at the bottom of the page to see what your topic will look like (use the BACK button on your browser to go back and fix something.), and finally
- click the `[ Save Changes ]` to save what you did.
-4. **But this is scary:** Anybody can do anything! Collaborating the Wiki way works because of the [[WikiCulture]]. (You can define fine grained [[TWikiAccessControl]] based on groups if really necessary)
+4. **But this is scary!** Anybody can do anything! The concept at first may seem...strange. Uncontrollable. And yet, collaborating the Wiki way works! See [[WikiCulture]]. (You can define fine-grained [[TWikiAccessControl]] based on users groups if really necessary, and there's full revision control that retains all changes!)
5. **Experiment:** To get your virtual hands dirty, visit [[Test|Test/WebHome]] in the %WIKITOOLNAME%.Test web.
-6. **Create a Link:** To link to another topic, start by editing an existing topic.
- - To create a link to a topic that already exists, type its `JoinCapitalizedWords` name (topics are automatically linked if they are [[WikiWords]], e.g. names composed of two or more words with initial capitals, run together).
- - To create a link to a page that does not yet exist, make up and type a `NeverBeforeUsedPhrase`. You are encouraged to include [[WikiWords]] in your content, for others to fill out later.
- - When you have saved the topic, and redisplayed it, the references to existing topics will be linked and the references to topics that don't exist will be followed by a linked "<u>?</u>" (question mark).
-7. **Create a Topic:**
+6. **Create a link:** To link to another topic, start by editing an existing topic.
+ - To create a link to a topic that already exists, type its `JoinCapitalizedWords` name (topics are automatically linked if they are [[WikiWords]], names composed of two or more words with initial capitals, run together).
+ - To create a link to a page that does not yet exist, make up and enter a `NeverBeforeUsedPhrase`. You are encouraged to include [[WikiWords]] in your content, for others to fill out later.
+ - When you've saved the topic, and redisplayed it, the references to existing topics will be linked and the references to topics that don't exist will be followed by a linked "<u>?</u>" (question mark).
+7. **Create a topic:**
- To write something up for a new topic, click on the "<u>?</u>" (question mark) that follows a [[WikiWord]].
- - To create a free-floating topic, e.g. a topic that is not linked from anywhere, type its [[WikiWord]] in the entry field at the top of any page. If the topic already exists you'll then be taken to it. If it doesn't exist, you'll then have the option to create it.
-8. **See the History of a Topic:** Check out the the various "Diff" entries at the bottom of page.
-9. **Attach Files:** Upload and attach any file to a topic by following the "Attach" link at the bottom of page.
-10. **Forms:** Use forms in topics to capture specific information e.g. for use in FAQs or bug tracking - see [[TWikiForms]]
-11. **Learn More**: The [[TWikiTutorial]] gives you some more details on the %WIKITOOLNAME%. [[WikiReferences]] has links to articles and books around collaboration and the Wiki technology in particular.
+ - To create a free-floating topic - a topic that is not linked from anywhere - type its [[WikiWord]] in the entry field at the top of any page. If the topic already exists you'll then be taken to it. If it doesn't exist, you'll then have the option to create it.
+8. **See the history of a topic:** Click the <code>**Diffs**</code> link on the control strip at the bottom of every page to see a complete history of edits for that topic.
+9. **Attach files:** Use your browser to upload and attach any type of file to a topic using the <code>**Attach**</code> link at the bottom of the page.
+10. **Organize:** Use [[TWikiForms]] to include specific information wiht individual topics - for example, classify pages by subject, status, or date.
+11. **Learn more**: [[TWikiTutorial]] takes you on a 20-minute tour of the TWiki essentials. [[WikiReferences]] has links to articles and books about online collaboration and Wiki technology in particular.
-**Main Features of %WIKITOOLNAME%**
+**Main Features of TWiki**
-- Edit existing pages or create new pages by using any web browser.
+- Edit existing pages or create new pages by using any Web browser.
- Web pages are automatically linked. You do not need to learn HTML commands to link pages.
-- Very simple text formatting. Basically, you write a web page like you would write an email.
-- Full text search with/without regular expressions.
+- Very simple text formatting. Basically, you write a page the same way you would write an email.
+- Fast, full-text search with or without regular expressions.
- All changes to pages and attachments are under revision control. Find out who changed what and when.
-- Fine grained access control based on groups.
-- Automatic email notification when web pages change.
-- File attachments: Upload and download any file as an attachment to a page by using your browser. This is similar to email file attachments, but it happens on web pages.
-- Topic locking: Users are warned if a page is being edited by an other person. This is to prevent contention, e.g. simultaneous page editing.
-- **_Read more_** about the tool at <http://TWiki.org/> .
+- Fine-grained access control based on users and groups.
+- Automatic email notification when pages change.
+- File attachments: Upload and download any file as an attachment to a page, using your browser. This is similar to email file attachments, but it happens on web pages.
+- Topic locking: Users are warned if a page is being edited by another person, to avoid simultaneous page editing.
+- Templates and skins: Customize every possible aspect of the look and feel of each TWiki installation, down to the individual page level.
+- Plugins: A growing collection of plugins allows you to easily add optional extended functions, or to create your own.
+- Support: An active, helpful development community keeps TWiki support and development constantly moving forward.
+- **_Read more_** about the TWiki at <http://TWiki.org/> .
**Starting Points in the %WIKITOOLNAME%.%WEB% web**
-- ** [[TWikiTutorial]] **: Familiarize yourself with %WIKITOOLNAME% before you start editing content.
+- **[[TWikiTutorial]]**: Familiarize yourself with TWiki before you start editing content.
- [[WebHome]]: Entry point of this %WIKITOOLNAME% web.
-- [[TWikiSite]]: Explains what a %WIKITOOLNAME% site is.
+- [[TWikiSite]]: Explains what a TWiki site is.
- [[GoodStyle]]: Things to consider when changing text.
- [[WikiSyntax]]: Easy to learn rules when editing text.
- [[WebChanges]]: Recent changes to the %WIKITOOLNAME%.%WEB% web.
-- [[TWikiRegistration]]: **Before you leave** add your name here.
+- [[TWikiRegistration]]: **Before you leave**, add your name here.
git://git.openafs.org / openafs-wiki.git / commitdiff