Using Wiki Documentation
From DGC Wiki
|
Where do I start?
Get a username and log in by visiting Special:Userlogin and choosing a username, password, and email address. Feel free to click on Special:Preferences to set your user preferences. If you're not a wiki expert, you should peruse the next section, otherwise, go ahead and skip it. You should also create a personal page asap; see below.
But I'm new to MediaWiki ...
If you've never used wiki, go to the Sandbox and click the Edit tab near the top of the page or Edit this page link at the bottom left (if you are using an old "skin"). MediaWiki accepts HTML as well as its own useful markup. Some highlights (you can get to these by using the javascript buttons up top):
- To make a link to another wiki page, enclose its name with "[[" and "]]" (no quotation marks). If you want another name to be displayed, use a pipe inside the double-brackets, e.g. "PageName|This is the pretty format of PageName that you want displayed".
- To make a link to a non-wiki page, enclose its name with "[" and "]" (no quotation marks). If you want another name to be displayed, use a space (rather than a pipe, as above) to separate the PageName and DesiredName.
- To make a headline, start a new line with the text between equal signs. The number of equal signs determines the level of the heading. Most pages start with a secord order heading (written == like this ==). If there are more than four headlines, they will be displayed in a table of contents.
- To insert a binary file, click on the text "Upload file in the sidebar (usually on the left side of the screen, under "toolbox") and follow the instructions there. NOTE THAT YOU WILL REPLACE any file that existed with the same name before, so check if it exists. The filename you upload will be preserved through the upload process so make sure it conforms to the naming conventions below.
- If you want to display an image inline in a wiki page, use Image:uploaded_file_name, otherwise, to link to its summary page using :Image:uploaded_file_name (NOTE the colon!).
- For non-image pages (i.e. not *.jpg, *.gif, *.png, etc.), use Media:uploaded_file_name to link to a file. To link to its description, use the :Image:uploaded_file_name convention.
- To make a bulleted list, put an asterisk "*" at the beginning of each line.
You can see lots of examples of how to format information the wiki by just clicking the edit button when you see something interesting.
How do I become A Wiki Badass?
You worship one of the Sysops ... seriously, read the MediaWiki User's Guide: Editing Overview
How this Wiki is Structured
Every team has a link on the Main Page (note that between races these links may not be present). Under each team will be general and then specific components, i.e. under Planning one would find trajFollower and ladarFeeder. You will also find:
- Meeting Notes
- Presentations
- Team-specific Guidelines
- checklists (referencing checklists below ... this is actually important)
- Activity Log (we made hotdogs on this day, drove bob off a cliff that day). Reference specific tests as well.
For each component, we will have
- functional spec
- user manuals
- manufacturer manuals
- checklists
- references, if applicable.
- link to applicable tests where possible
What about photo albums?
Since there does not seem to be a way to batch upload files to the Wiki, it can be a long and tedious process to upload an entire set of photos to the Wiki. This is why we have set up a place for these at http://gc.caltech.edu/media/pictures/. Just create a new directory on grandchallenge and scp your photos to there. You can then use 'jpgind' to generate an index for your collection and link it to the wiki (or wherever).
Things that don't go in the Wiki
... everything else does!
- Test logs and their README's (these should be stored in the grandchallenge filesystem and accessible from the internet).
- Source code and functional documentation (this is in subversion/cvs and should be accessible from the internet).
- Stuff that goes in Bugzilla or PhpBB.
- Photo albums (see above section).
Making New Pages
- Navigate to where your documentation should go
- Edit the page to create a link to the name of your new page (using the naming conventions stated below, of course)
- Save
- Click on the link, where you can automatically begin editing
- Note that when you create a link but it doesn't link to anything, Wiki automatically displays the link in red. So if you've just wrote some documentation and linked to some pages and you see red links, it means those pages either don't exist or you linked to the wrong page.
In short, don't start your page immediately; create the link first.
Naming Conventions
- For page titles, you can either capitalize each word or just the first word. Wikipedia tends to use the latter, so that you can reference something in a sentence without having to recapitalize the link.
- For attachments - this is for uploading; name it something reasonable in the link
- (team_name)_(component_name)_(short descriptor).(filetype)
- Ex: Embedded_Vstate_Software.doc
- For dated things, put dates at the end, using dashes to separate fields (starting with the year):
- (team_name)_(component_name)_(short descriptor)_(YYYY-MM-DD).(filetype)
- Ex: Project_Meeting_2004-05-05.ppt for a file from 5 May 2004.
Nice things to do
- When putting in new pages, put a link at the top to the page you linked from, i.e. if you're putting in a page for the brake under the embedded index, link back up to the embedded index
- Put spaces between words in the names of Wiki pages, for readability.
- Put spaces in Wiki page links instead of underscores, e.g. "Documentation Team Index" instead of "Documentation_Team_Index".
- Put the word "Documentation" in Wiki pages that represent actual functional/user/developer documentation. That way it will be found if you search Wiki for "Documentation".
Personal Pages
- How to make one
- Once you've made yourself a login, you can make your own page.
- Click on your username in the top right-hand corner
- Voila.
- What it should look like:
Wiki Versions
Mediawiki 1.4.5
What's New in version 1.4.5 (including local installation changes):
- Latex equations now work (see bottom of User:Murray page)
- Thumbnails should be working (not tested)
- Security fixes
Mediawiki 1.6.x
The latest version of the mediawiki software (as of May 2006) has lots of new features. Some of the ones that are more useful for this wiki are:
- Better support for extensions. See the Change Log for a list of some of the ones we have installed.
- Ability to generate e-mail when changes are made to watched pages
One annoying (but probably good) think about v1.6 is that it requires you to use proper syntax for HTML tables. This means that some older pages may have incorrect formatting. Please fix the page if you see one that has a problem (you usuall need to add </td> and </tr> tags to close off the corresponding <td> and <tr> tags).
--Richard Murray 13:18, 10 June 2006 (PDT)
![[Main Page]](../../../../upload/alice.jpg)