Wiki Survival Guide
This page gives "best practices" for using the OSAF wikis.
Basics
Q: What's a wiki?
A: Briefly, a wiki is a Web site that can be collaboratively edited via the Web. C2, an external site, has detailed information on what wikis are and how to use them.
The OSAF wiki is organized into several areas, called "WikiWebs". You can switch between
the different WikiWebs by clicking on the links at the top of each page. If you don't know which WikiWeb you want, then see the OsafWikiWebStructure. You can sign up for WebNotify separately for each WikiWeb.
Q: What do I need to do to start using the wiki?
Read more of this page for help. If you are ready to create or edit one of the pages on this wiki site, please register.
Q: How do I create and edit pages?
See Creating Pages and Editing Pages below.
Finding stuff
Q: How is this organized?
A: There are three WikiWebs. See OsafWikiWebStructure for what is on each WikiWeb.
Q: How do I search?
A: There are several search facilities:
- the search box in the upper colored bar of each wiki page
- the Advanced Search link at the top of the left-hand sidebar
- the GoogleWikiSearch link just below the Advanced Search link on the sidebar
Q: Wiki searching turned up nothing!
A: A few things to check:
- You might be searching the wrong WikiWeb. Clicking on the "All public Webs" box will search all the WikiWebs.
- The Search page lets you choose matches in the name of the page (e.g. WikiSurvivalGuide or WebHome) or in the body of the text. You might try clicking on the radio button "Both" on the Search page.
Q: I did a GoogleWikiSearch for a page that I know exists, but the search turned up nothing!
A: Google only crawls the wiki occasionally, so Google's index might be out of date.
Q: Can we have a better search, one that does relevance ranking like Google yet is up-to-date?
A: The plan is to install the nutch search engine into our wiki, which has good relevance ranking.
Q: I still can't find it!
A: Final search suggestions:
- Try looking through the entire tree of the appropriate WikiWeb, e.g. PageTree.
- Tell MikeT. It helps to know what specific things are hard to find.
Q: It takes me too long to get through the navigational structure to find documents that I need regularly! What can I do about that?
A: How about bookmarks?
- Bookmark wiki pages in your browser
- Make a "bookmarks list" on your Wiki home page. (See TedLeung for an example.)
- If you have a list of bookmarks that might be useful to others, you can create an index page on the Wiki somewhere. (MikeT can advise you of whether such an index would be useful, where it should go, and/or if there is an existing index that you could augment instead.)
Monitoring changes
Q: How can I find the pages that are most popular or that have changed recently?
A: There are several things you can do (most of which are also listed on the useful WikiInformation page):
- Add yourself to WebNotify for each of the WikiWebs you are interested in. The wiki will then send you email every day at midnight:01 California time, telling you about all the pages that changed:
- Look at the WebChanges page for the WikiWeb that you're interested in. (Note that on any search results page, including WebChanges pages, there is a link next to the diffs icon (
) that will show you just the changes for the page.)
- Subscribe to an RSS feed for the WikiWeb that you're interested in:
- Projects WebRSS?
- Documentation WebRSS?
- Journal WebRSS?
- Subscribe to an RSS feed that gives links to the diffs pages for pages that changed recently in the WikiWeb that you're interested in:
- Chandler WebRSSDiff?
- Documentation WebRSSDiff?
- Journal WebRSSDiff?
- If you are interested in a specific area, you can make a table to show the most recently changed pages that mention a specific string. (See GrantBowman and RepositoryFramework for examples.)
Q: How can I find what has changed on a page?
A: Click on "Diffs" in the row of links at the top of the page.
Q: How can I find pages that link to this page?
A: Click on "Linked-from" in the row of links at the bottom of the page.
Creating Wiki pages
Q: How do I create a new page?
A: That's completely non-obvious. To add a new page, edit an existing page to put in a WikiWord to act as a link to the new page. The link will then appear with a question mark after it on the existing page. Click on the question mark, and the new page will be the creation page for the new topic. (The question mark will go away when you finish creating the page.)
Q: Where should I put a page?
A: First, put your page in the right WikiWeb. Current active and updated project information goes in Projects. If it's quickly-outdated information or a point-in-time proposal, (like a status report or meeting minutes), put it in the Journal. A good starting point for just about anything is your own ContributorNotes page or in TimestampedProposals. (See OsafWikiWebStructure for more on the WikiWebs.)
Q: What kinds of page names give the TWiki software trouble?
A: There are several kinds of page names that the Wiki has trouble with:
- names that are not WikiCase (e.g. Process or Design or OSAFDesign or DesignUI?)
- names with hyphens or other punctuation (e.g. FredThoughts?-2-Feb-2004 or WhatIsChandler??)
Acronyms cause problems, so you should downcase all but the first letter of an acronym, e.g.
OsaFoundation instead of OSAFoundation or FooAclList instead of FooACLList. Yes, it's ugly, but you can always make it more beautiful by explicitly specifying a display string, e.g. [[OsaFoundation][OSAFoundation]].
Q: Just what kind of trouble does it give the software?
A: There are various scripts that operate on the wiki that have a hard time recognizing strings as being WikiWords if they are not WikiCase. You can see this by looking through JungleWikiTree.
Q: Why don't Glossary pages have WikiCase?
A: Because BrianDouglasSkinner fought hard to get a special dispensation for glossary terms.
Q: What other wiki page naming conventions does OSAF have?
A: In order to make it easier to search for a given type of pages, please
- put the date at the end of the page name and use YYYYMMDD format (e.g. 20031210) in the Journal
- use "ZeroPointX" in the pages about "dot" releases instead of combinations that use "Oh", "", and "Dot" -- WhatIsZeroPointThree instead of WhatIsDotThree, for example.
Q: What other advice do you have for naming pages?
A: If you can't decide between giving a page a plural name and a singular name (e.g. FooThing vs. FooThings) you're usually safer using the singular name. If you type FooThings when your page is named FooThing, the wiki will still take you to the correct place. For example, TestSingulars will take you to the existing page TestSingular. Note however, that if someone goes to the page via a URL, if you type plural when the name is singular, then the lookup will fail. For example, http://wiki.osafoundation.org/twiki/bin/view/Jungle/TestSingulars will fail.
Q: How do I rename a page?
A: See below.
Editing Wiki pages
Q: How do I edit Wiki Pages?
A: At the bottom of each page is a toolbar with "Edit" as one of the options. Click on "Edit" and type into the text box. You can just type in straight text, but using wiki markup will make it look better. (You can also use HTML if you want.)
When you are done editing, click on the "Preview" button to see what the page would look like before you commit your changes. (Note: on the Preview page, all links take you to a page that warns you that the page hasn't been saved yet. This is to help remind you to save the page.)
If you like what you see, click on the button marked "Save Changes", and the page will be saved.NOTE: If you forget to save the page, you can lose all your edits! Your text will be saved in your browser's cache for a while, but if you close the browser window, you probably can't get your changes back.
Q: What format do I need to use to write pages?
Wiki formatting is very easy. Just type plain text with blank lines between paragraphs. To get fancier you can use raw HTML or TWiki formatting. There is a one page summary of the editing format, hints at the bottom of each editing page, a longer document on how to format, and hints on good style.
Q: How can I make the edit window bigger?
A: On your "Wiki home page", there are a bunch of preferences that you can set. For example, to make the box wider, set EDITBOXWIDTH. To make it taller, set EDITBOXHEIGHT.
Q: What do you mean by "your 'Wiki home page'"?
A: It's a page in the "Main" WikiWeb (also known as "Main") associated with your login. For example, Ducky's is DuckySherwood.
Q: How can I do wiki editing off-line?
A: Before you go off-line, edit the page, then copy and paste all of the text in the edit box into a text editor. You can now edit to your heart's content. When you go online again, you can paste your changes in.
Q: Is there any way to make my browser open a wiki TEXTAREA in my favorite text editor?
A: Yes. There is at least the Electrix extension to Mozilla. We have tested this to work at least in this configuration: Windows XP, Mozilla 1.6, Electrix 0.3, XEmacs 21.4 (patch 13). One major caveat with this is that while you are editing, Mozilla is totally locked down and will only resume once you quit the external editor.
Q: Are there any Browser-based WYSIWYG wiki editors?
A: Some, see the wikipedia entry for wiki editors etc.
Q: Is there a cross-browser wiki-plugin? Is there a WYSIWYG editor?
A: Not that we know of. Please find us one. 🙂
Q: Do you have any style guidelines?
A: A few:
- Remember that we have an international audience.
- Please use the dd mmm yyyy date format (e.g. 10 December 2003) in text. (The YYYYMMDD format is for names of pages.)
- Non-native speakers of English also sometimes have trouble with prepositional verbs, especially figures of speech, e.g. "deal with", "pay up", and "kiss off".
- Please avoid slang, colloquialisms, and obscure words.
When creating a page, please start with your main point, follow with further explanation of the "what", then explain "why", and end with references to external sources. (See also WxWindows, which has explicit clarifying headers.)
You could create a wiki link with a full URL, e.g. http://wiki.osafoundation.org/twiki/bin/view/Journal/StaffMeetingNotes. Please do not. If you use standard wiki notation (e.g. Journal.StaffMeetingNotes), then the wiki can change all of the references to that page automatically. There isn't a facility to update URLs automatically.
Q: When do I have permission to edit something?
A: It is always okay to make changes:
- to fix typos, misspellings, or grammar errors,
- to fix broken links, and
- to add comments
For things in the
Projects WikiWeb, you should probably communicate your feedback to the page owner and let them make the changes.
For things in the
Documentation WikiWeb, be careful that your changes improve the documentation for a wide set of readers. You can also make comments (we may sometimes create separate pages for Documentation area comments).
For things in the
Journal WikiWeb, you probably shouldn't make more than grammatical changes unless it's explicitly a collaborative effort. Comments at the bottom are typically quite fine, of course. You are also encouraged to make your own Journal pages relevant to any of the work we do.
Q: When do I have permission to add a page?
A: Any time! If you add a page in the Projects WikiWeb, we ask that you maintain the page (or move it to Journal when the page is no longer maintained).
Moving, deleting, and rearranging Wiki pages
Q: How do I change the name of a page?
A: On the bottom toolbar row, on the right-most end of the row, click on "Move". On the next page, click on rename/move topic in all public webs. The next page has two boxes at the top -- one for which WikiWeb to put it in and one to give it the new name.
Below the boxes are a bunch of pages listed that link to the page you're about to move. If you don't clear any checkboxes and click the Move/Rename button, the wiki software will magically update the links on that page to point to the new page. You can click a checkbox next to a page if you think that page shouldn't get updated.
Next, click near the bottom of the page on the button labeled Rename/Move. IT IS EASY TO ACCIDENTALLY CLICK ON THE "Clear all checkboxes" BUTTON. DO NOT DO THIS UNLESS YOU DON'T WANT ANY PAGES TO GET UPDATED.
Note that I simplified a tiny little bit: the list of links includes pages that have the text of the link on it. For example, if you change the name of page named SecretMagicRecipe to NewAndImprovedRecipe, any page with the non-link text "secret magic recipe" will also show up on that list. Fortunately, the wiki software will not change the non-link text "secret magic recipe" to "New And Improved Recipe".
Q: How do I move a page to a different WikiWeb
A: Rename the page, using the instructions above, and rename it to a different WikiWeb.
Q: How do I delete a page?
A: Press the "Move" link or "Delete" link at the bottom of the page, then move the page to the Trash WikiWeb following the instructions above for renaming.
Q: How do I change the parent of a page?
A: Click on the Reparent link, then look at the third section on the page that shows up. In the selection box labeled "Set topic parent to:", scroll to the name of the page that you want to be the new parent. After you have selected a new parent name, click on Edit. On the new page, click on the Preview Changes button, then on the Save Changes button on the next page. Yes, it really does take a minimum of five mouse clicks to change the page parent.
Attachments
Q: How do I attach a document to a wiki page?
A: When viewing the page, go at the bottom of the page. Click on "Attach" in the bottom link bar (right next to Edit) and follow the instructions.
Q: How do I update an attachment?
A: If you have already attached a file to a Wiki page, clicking on "Attach" at the bottom of the page and then "manage" next to the file will allow you to upload a newer version of the file while retaining the same file name and Wiki links.
Q: I want to attach a document, but I don't want to have to go through all the bother of the wiki attach process every time I change it. What else can I do?
A: Post the document on a Web site somewhere and just put in a link to it on the page. For OSAF employees, you can put it in your public_html directory on kahuna.
Q: How do I delete an attachment on a wiki page?
A:
- At the bottom of the page click on the "Attach" link.
- Then for the attached file you wish to remove click on the "manage" link next to the name of the file.
- At the bottom of the page click on the "move attachment" link. Select Trash as the web you want to move the attachment to and rename the topic "TrashAttachment" as the Note: at the bottom of the page suggests.
- Finish the deletion (actually moving the attachment to the Trash Wiki on the page TrashAttachment) by clicking the "Move" button at the bottom of the page.
Advanced Wiki-Fu
Q: How can I include one page in another?
A: Using the %INCLUDE% variable. Hint: if you want to include only a piece of the page, you need to use %STARTINCLUDE{"nameOfPage"}% and %STOPINCLUDE% variables to delimit the piece you want to include. See ChandlerZeroPointThreeReadme for examples.
If you want to include more than one section of a page somewhere, you need to used named sections. At the beginning of the section, put %SECTION{name="nameOfSection"}% and end with For example, %SECTION{name="currentPlan"}%. To end a section, use %ENDSECTION%. On the including page, use %INCLUDE{"nameOfPage" section="nameOfSection"}%, e.g. %INCLUDE{"ApplicationProject" section="currentPlan"}%. See CurrentCombinedStatus for examples.
Q: Can I include an arbitrary file -- such as an HTML document -- in my page?
A: Yes, if it can be reached by a URL. Caution: it can be slow to load pages with external INCLUDES.
Q: How do I add a table of contents?
A: The %TOC% variable will make a table of contents of all the headers on a page. See this page for an example.
Q: How can I insert those cute graphics like 
and 
?
A: There is a list of standard icons and a list of OSAF-specific icons. (View the appropriate page source to see what the variable is named. is %S% and is %Y%, for example.
Q: How do I make tables?
A: See TextFormattingRules. One thing that is hard to notice is that if you want an empty cell, you need to put at least one space between the vertical bar: "| |". If you want to span columns, put in cells with vertical bars but do not put anything between the bars: "||". Look carefully in TextFormattingRules to see how it's done.
Q: How can I add a "most recently changed" table?
A: With the Wiki %SEARCH% function. View the raw text of GrantBowman and RepositoryFramework for examples.
Q: What's an Edit Table?
A: An EditTable allows you to fill out tables using edit fields and drop-down menus. They are pretty cool, but (warning!) they can break INCLUDEs; see below.
Q: Is there an easy way to link to bugs in the OSAF Bugzilla database?
A: Yes. Just type "Bug:" and then the number, e.g. Bug:1001. The link will be made magically for you. Note that there is a bug such that if you do this in a table, there must be whitespace to the right of the bug number and to the left of "Bug".
Q: Is there an easy way to link to RFCs?
A: Yes. Just type "RFC:" and then the number, e.g. RFC:2822. The link will be made magically for you. Note that there is a bug such that if you do this in a table, there must be whitespace to the right of the RFC number and to the left of "RFC".
Q: Are there other magic prefixes like Bug and RFC?
A: Yes -- see for example, Wikipedia:byzantine+empire, GoogleGlossary?:read the fucking manual, Google:osaf. Note that if you want to pass a multi-word string, you have to use "+" instead of spaces.
Q: Can I make other magic prefixes?
A: If there is a service that has URLs that have very regular URLs, you can probably make magic prefixes for them. See InterWikis.
Q: Is it possible to pull individual fields out of a table?
A: Yes, though that's some serious wiki-fu. See ThirdPartyCode for an example.
Q: Where can I learn more advanced stuff?
A: There are zillions of TWikiVariables that you can set to do cool things.
Q: What else?
A: Visit the http://TWiki.org Codev & Plugins webs. Grant Bowman has also put together WikiPowerUserHints.
Miscellaneous
Q: Why is "Main" called "Main" and why it is so uninteresting?
A: Last time we gathered input for a wiki redesign, people mentioned that searches returned a lot of pages that were completely uninteresting. One of the least interesting sets of pages was the users' Wiki home pages, so we split that off into a different WikiWeb. (That allows people to easily exclude them from the search.) Originally, the idea was for that WikiWeb to be called "Users". Unfortunately, because of how the Wiki code is set up, user pages must be in a WikiWeb named "Main".
Q: Can't you change the code so users could be in a WikiWeb called "Users"?
A: Well, we could -- but in addition to taking time away from cool things (like putting in a better search engine), that would make our code diverge from the official Twiki source. That would make it harder for us to upgrade.
Q: How do I get an account so that I can edit pages?
A: On TWikiRegistration.
Q: I forgot my password! What do I do?
A: Email support@kei.com.
Q: How do I change my password?
A: On ChangePassword.
Q: How can I print without all the header and footer gunk?
A: To get a "clean" page, either click on Printable near the upper right of the page (on the same bar as Edit), or add "?skin=print" to the URL of the page.
Q: When I try to save the page, I get an error telling me that I need to save the page! What do I do?
A: This is a bug. This has happened sometimes when you try to INCLUDE a page that has an EDITTABLE on it. You can work around it, but it's cumbersome. If the page you're trying to save is called FooPage and the page with the EDITTABLE is
FooTable, do this:
- edit FooTable
- break the EDITTABLE (removing the terminal "%" will do the job)
- save FooPage
- edit FooTable
- fix FooTable's EDITTABLE
- save FooTable
-- LisaDusseault - 02 Feb 2006
- Access restriction:
- Set ALLOWTOPICCHANGE = TWikiAdminGroup
- Set ALLOWTOPICRENAME = TWikiAdminGroup
