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.
If you need editing help, please check out the online documentation. 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.
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.
User Pages
See Help:User page for more details about user pages.
Every registered user on the VrlWiki has a corresponding "user page", the title of which has the format "User:<username>", as in User:Jadrian Miles. User pages should contain information about the particular user, including links to other websites and perhaps a short profile. Pages related to the user, such as planning documents and draft documents, should be subpages of the user page. A rule of thumb is that if an article's title would have your name in it, it should be a subpage of your user page instead of a standalone 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! 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. 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.
Uploading files is easy: just click the "Upload file" link to the left. For more details, see Help:Managing files.
How to Request Things to be Added to the Wiki
Sometimes you know that something is missing from the wiki, but you yourself can't fill in the gap. That's okay; we use discussion pages to write down content suggestions. If you have a small or abstract suggestion about the content of a particular 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. If a page's content is incomplete, please also tag it as a "stub" by adding the following code to the top of the page:
{{stub}}
If you think a page should exist but you don't have anything to put on it, go to the main discussion page and make your suggestion there.
If a particular page has style issues, doesn't have appropriate links to other articles, or was obviously copied and pasted from somewhere else and needs to be refined for the wiki, please add the following code to the top of the page:
{{wikify}}
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 the Brown computer network, read-only anywhere with our group password, and read-write only with a login. Outside of the Brown network, no one without the proper password can see the wiki at all.
Read Permission
Anyone connecting to the wiki from within the Brown network has unfettered read access.
Users connecting to the wiki from outside the Brown network will be presented with a pop-up server login box. The server restricts access of any kind to the directory in which the wiki lives, and it requires a password to access this directory. The server login is completely distinct from the VrlWiki login. There is a single shared username for the server login: "vrluser". The password is secret; talk to David or an advanced PhD student to get it. If you know it already, please give out the vrluser password only to collaborators, fellow researchers, and relevant students! Anyone outside of the Brown network who does not know the "vrluser" password will not be able to connect to the wiki at all, neither for reading nor writing.
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
- Click the "Log in / create account" link in the upper right corner of the page.
- On the login page that appears, click the "request one" link.
- Fill out the registration form, including a couple sentences of biography (otherwise the form will complain).
- You will receive an email to confirm your email address. Click the link in the email.
- The wiki administrators will receive an email to approve your sign-up request.
- 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.
- Click the "Log in / create account" link in the upper right corner of the page.
- 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.
- Click "Log in".
Precautions
Despite our access controls, you can't really be sure who's reading information on this wiki---remember, anyone on the Brown network can read VrlWiki pages. 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.