CJMP Wiki Best Practices

From CJMP Wiki
Jump to: navigation, search

Using the wiki: it's more than learning the markup and navigation). You can make your contributions more useful and help make the wiki more friendly - here are some things to know.

It should go without saying (this is a wiki, after all) -- if this is missing important stuff, by all means, add it!

Working collaboratively? Use the wiki!

If you are working in a group on describing a process, developing a training session, working up a proposal, composing a brochure -- anything collaboratively developed that does not require secrecy due to legally-sensitive information -- put it on the wiki! Emailing documents back and forth leads to version clobber, and sharing your work makes it easier for others to build on it in the future.

Choose titles wisely and link 'em up

Ideally, you want what you are writing to be referred to. Not coincidentally, the easiest way to create a page is to make a link on another page to the title of the page you're going to make, and follow that red link. But it pays to be aware of other related pages on the wiki where a link to your document might be relevant; go ahead and add it! And please, make your title simple and descriptive and easy to link to. For example, Director for the Environment rather than "Job description for environment director seat." That way, future pages talking about that position (idea/program/process/joke) will be able to easily point to the relevant page. Capitalisation also matters -- since the wiki cares whether letters after the first are capitalised, keeping it lower-case will make future linking easier.

"About this document" sections

If you're working on something that might become policy, or has become policy, or is/will be used by a particular group, or is a historical page being (re-)integrated into current reality, or it shouldn't be edited by anyone else, adding a section "About this page" can be useful. Include in it:

  • the name of the group/individual working on it
  • whether it is an adopted policy of Free Geek or one of its internal groups
  • links to any minutes of meetings that are relevant (minutes for all groups, even ad hoc ones, should go to the minutes list)
  • dates of relevant meetings (if it was approved as policy, etc.)
  • next steps expected

And don't forget to update your baby when the status changes. This is extra work, but it will make things clearer in the future.

Talk pages

Every wiki page has (at least a potential) talk page. This page is for discussion about the main page -- hashing out a section that might be controversial, pointing out elements that need work. This page is for people who are collaborating on a page, not for content that you want to be generally available to wiki-browsers, linked to from inside or outside the wiki. If comments (see above) end up being long, it may be time to take it to the talk page to keep the main page readable (perhaps with a note that there is discussion on the section in the talk page, so people who are interested can follow up).

Substantial content should be on pages within the main wiki namespace.

Use categories

An important part of linking up your page within the wiki is putting it in the appropriate category or categories. You can check the Categories list to see if there's something relevant, or look at related pages. Often the relevant category will be the name of the group that is responsible for the page or that the page pertains to.

Link to outside information

As mentioned in the "about this document" section, link to relevant meeting minutes/email discussions/wiki pages/outside world pages wherever such a reference might be useful for a reader to contextualise your information. Remember that your reader may be from the future or even alien (ok, from outside CJMP), and should not be assumed to know everything (especially how to find things like records of decisions). Try to keep that audience in mind when writing and linking.