Freekiwiki best practices

From FreekiWiki
Jump to navigation Jump to search

Using the wiki: it's more than learning the markup (and navigation, and netiquette). If you've clicked around a bit, you can see that it gets a bit confusing in here. Some stuff is out-of-date. Some is orphaned in little back eddies. Some makes reference to acronyms or committee names you've never heard of. 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 class syllabus, 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. Capitalization also matters -- since the wiki cares whether letters after the first are capitalized, 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 is part of your MFA final project and 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, and ties the wiki closer to FG's other documentation.

Attribute your comments

You can make comments on wiki pages. It's easy: use a colon at the beginning of your comment, and it will be indented.

Like this.

But that's not all. You should also attribute your comments so that people know who said that, and when. You can do that with tildes: --~~~~

Like this --Ideath 00:17, 15 July 2011 (UTC)

Ideally, comments will lead to other comments, and eventually, the discussion will be integrated into the main document. And the discussion will be retained in the history of the page.

A comment.
A comment in response.
Ah, we are agreed.

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 contextualize your information. Remember that your reader may be from the future or even alien (ok, from outside Free Geek), 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.

Includes to know

Here's a good one: {{draft}}

This will put a note in your document that it is a draft and under development, inviting people to participate. It also adds the draft category tag to your document, so it turns up in the list of drafts. Be sure to remove the draft include when your document is finalized!

Other includes are pretty nifty, like {{FreekBox Specs}} (includes the freekbox specs, so when they change it is updated all around) and {{Minutes}} (inserts a meeting minutes template into the page when it is saved, to make it easier to structure minutes).

When you don't have the time

If a page needs to be made but you don't have time to do it justice, use the template {{Stub}} -- this makes it clear that the page is a placeholder for something more involved.

If you come upon a page that is out-of-date but don't have time to fix it, add it to the category "Needs Update." And if it's just plain useless and you don't see how it would ever add to the world's understanding of Free Geek, maybe add the Delete category tag to it, so wiki admins can clean it up.

Ancient history

I imagine we may want to consider adding a "Free Geek History" category for pages that are out-of-date, will not be updated, and might be illuminating to future FG aficionados. But i haven't done the research on that yet (maybe it already exists), so i'm not advising. --Ideath 00:17, 15 July 2011 (UTC)