VrlWiki

The VrlWiki is a wiki for use by the Brown Visualization Graphics Lab to store project documentation, organizational documents for the group, and information to help researchers in the group work better. A wiki is a system for organizing, accessing, and storing long-term living documents that anyone (with the right permissions) can edit. Basically, if there's information that ought to be recorded for people to look up, it belongs here, and adding it is easy. Storing information in a wiki allows anyone in the group to refine it over time, so that it's always up-to-date and as helpful as it can be.

This article explains the information that we store in the wiki and how we structure it, how you can add the information you know to this repository, and technical details about the access protections we use.

Content Policy and Wiki Structure

A wiki generally does not have a hierarchical structure; rather its pages are organized into an implicit structure by links between them and by the categories that group them together in intersecting sets.

For the purposes of our research group, however, it makes sense to have some small hierarchies; for example, the documentation pages, planning pages, bug tracking pages, and data tracking pages for a particular project should in some sense "belong" to that project. To create hierarchies, we use subpages.

Since a wiki is just a system for creating and maintaining interlinked documents, it can also contain its own development documents. We keep comments about content separate from the content itself in a structured way using talk pages.

Categories

See Help:Categories for more details about categories.

The main page grossly divides the content of the wiki into four main categories: group organization documents, documentation for the IT tools that help us do work in the VRL, documentation for projects, and HOWTOs. There are other categories and sub-categories, however; to see all the different categories that already exist, check out the list of categories.

VRL

Documents in the "VRL" category include documentation about what our group does at the high level, about our weekly meetings, about the group's and individual members' plans and goals, and so forth.

IT Tools

We have a few different IT tools in place to help us get our work done, including $G and its associated build system and the very wiki you're reading. The wiki entries related to these tools should include technical documentation as well as task-oriented user documentation linked to from the HOWTOs.

Projects

As a research lab our real product is new knowledge. Any given research project may encompass several different software tools, experiments, and publications, in addition to being a general concept unto itself. The documentation for the project should therefore include an overview, notes for the researchers working on it, bibliographies and reading lists, and user and programmer documentation.

Please keep in mind that almost every project lives on beyond the tenure of the researcher who began it. Documentation is crucial to the long-term usefulness of the tools and knowledge you create. This wiki is only visible to our lab and its collaborators, so please be as open about sharing information as you can.

HOWTO

There are a number of tasks that just about every researcher in our group has to do at least once. Choosing a project, writing software and papers, presenting your work, finding a job: all of these tasks are easier with a little guidance. Each HOWTO is an article devoted to a single task and describes in plain language the best way to accomplish it. Keep in mind that the audience for a HOWTO is a complete beginner; the reason someone is reading the article is because they don't know what they're doing.

Subpages

See Help:Subpages for more details about subpages.

Our wiki allows explicit page hierarchies in the form of subpages. The title of a subpage has a slash character in it, essentially like a directory path in Linux; for example, CavePainting/bugs and feature requests. The wiki automatically generates links at the top of a subpage to its ancestor pages.

Subpages should be used to organize pages that are strictly encapsulated by a single concept. For example, bug tracking pages, planning documents, and software documentation should be placed on subpages of their parent project. Standalone concepts, like significant software projects (e.g. CavePainting or the Diffusion MRI Pipeline), should have their own standalone pages and should not be recorded on subpages.

Discussion / "Talk" Pages

See Help:Talk pages for more details about Talk pages.

Every page has a tab at the top labeled "discussion". This is the page's "Talk page", where discussion about the content of a page should go. Generally speaking, notes about future content for a page should be placed on the Talk page (in a separate section, created using the "+" tab at the top of the Talk page) rather than on the page itself. The rule of thumb is that the audience of an article page is readers interested in the topic described by the title of the page, while the audience of a Talk page is the editors of the associated article page. For example, if you are addressing people interested in CavePainting itself, you should be writing on the CavePainting page; if you are addressing people interested in maintaining the CavePainting page, you should be writing on the Talk:CavePainting page.

How to Contribute to the Wiki

If you find an article confusing, misleading, incomplete, incorrect, or just plain ugly, please hit the "edit" tab at the top of the page and fix it! If you have a small or abstract suggestion about the content of the page, rather than something actionable that you can edit the page itself about, click the "discussion" tab and add a new section for your suggestion. For more details, check out Help:Editing pages.

If you think a page should exist that doesn't, either click a red link to it (red text on pages indicate links to other pages that don't yet exist) or type its name into the search box on the left. If you don't want to create a new page, go to the main discussion page and make your suggestion there. For more details, check out Help:Starting a new page.

If you'd like to contribute something but you don't know what, try browsing the list of pages that need attention.

If the software of the wiki itself is missing a feature you'd like it to have (say, easier syntax for some common task), please add it to the VrlWiki feature requests page and hopefully the wiki administrator will be able to implement it.

Security Features

Access is read-only without a password within CS, read-only anywhere with our group password, and read-write only with a login.

Read Permission

Anyone connecting to the wiki from within the Brown network has unfettered read access. Those outside the Brown network will need to use the standard "vrluser" username to log in. Please give out the password only to collaborators, fellow researchers, and relevant students!

Write Permission

Writing to the wiki is restricted to registered users only. Each new account is vetted by dhl and accounts will only be given to authorized individuals. In order to make the edit history of each document clear, each user's username is their full name; that is, David logs in as David Laidlaw, and Jadrian logs in as Jadrian Miles.

Registering for a Wiki Account

1. Click the "Log in / create account" link in the upper right corner of the page.
2. On the login page that appears, click the "request one" link.
3. Fill out the registration form, including a couple sentences of biography (otherwise the form will complain).
4. You will receive an email to confirm your email address. Click the link in the email.
5. The wiki administrators will receive an email to approve your sign-up request.
6. Once an administrator has approved you, you will receive another email saying so.

Logging into the Wiki

Once your login has been approved, you can log in to edit.

1. Click the "Log in / create account" link in the upper right corner of the page.
2. Fill out your username (remember, it's your full name) and password.
   • If you'd like to stay logged in indefinitely, click the "remember my login" box.
3. Click "Log in".

Precautions

Despite our access controls, you can't really be sure who's reading information on this wiki. Per-page access control are hopefully coming in the future, but in the meantime please do not post passwords or sensitive information, especially about human subjects in our research projects, on the wiki.

Special Editing Tricks

Embedding Complex HTML

Only wiki administrators can enable complex HTML, and they do this by creating special embeddable pages. If you have something you'd like to include, please look up a member of the "sysop" group in the wiki user list and ask them to set it up for you. The following are the embeddable pages that already exist.

Google Calendar

Template:gcal adds a Google calendar to the including page. The template looks like this:

{{#shtml:Template:gcal
|src=<a_long_ID_string>
|mode=[AGENDA|WEEK|MONTH]
|height=500
}}

Note that you must include values for each argument. Figure out the values by the following procedure:

1. Open up Google calendar.
2. Select the drop-down menu for the calendar you want and select "Calendar settings".
3. Scroll down to "Embed This Calendar".
   • You may also want to click the "customize" link to get other options.
4. In the text box containing the embed code, look for a string like http://www.google.com/calendar/embed?<key_1>=<val_1>&amp;<key_2>=<val_2>...
5. For each of the arguments above, look for the corresponding key in the embed code and set the argument to the corresponding value.
   • src will be a long string, probably ending with "group.calendar.google.com".
   • mode is one of AGENDA, WEEK, or MONTH.
   • height is 500 by convention on our wiki but you may choose any height in pixels.