Tips for writing wiki pages

From Cohen Courses
Jump to navigationJump to search

Before you start

Look at some example pages to get an idea for what's expected. Search in the wiki to see if it's already there - or if something very related is already there.

Writing Style

Use a narrative writing style. It's not easy to read a bunch of itemized lists...even if it seems easier to write them.

The purpose of the semantic links to to identify things that are conceptually prerequisites for understanding the paper. You should use this when you write. If you use a semantic link to a Method, Problem, or Dataset page, write your entry as if the reader is familiar with the contents of the linked-to page. Aside from material pointed to be the semantics links, however, your entry should be self-contained - i.e., readable to someone that is beginning the course.

For paper pages, the semantic links establish a model of your audience: it's someone like you, that already knows the semantically-linked-to material, that wants to understand the main points of the paper. Given that audience, try and be both concise, and precise. Think about the paper, and say what you think is important to know about it. If you see non-obvious connections to other work, explain them.

Don't intersperse a description with lots of opinion or questions - it's ok to have a section with questions and commentary at the end, if you want, after the paper has been summarized. However, it's expected that you actually understand a paper/method/problem/dataset if you're writing it up.

Naming your page

For a paper page, name your page something that would be reasonable citation entry, including at least the first author and the year, as in the examples. Squeeze in a conference name or an abbreviation of a journal if it's someplace easily recognizable to the audience - that will help them remember. You can move you page later if you need to, so this isn't critical.

For a method page, name it according to a reasonably long name of the method - eg, use Logistic Regression, not just "LogReg" or "LR".

Semantic links

In brief, the named links you should be using are:

  • Category links a new page to one of the pages paper, method, dataset, or problem.
  • UsesMethod links a paper to a method.
  • UsesDataset links a paper to a dataset.
  • AddressesProblem links a paper to a problem.
  • RelatedPaper links a paper to another paper.

If the page describes a paper, include a link of the form [[Category::paper]], like this: "This seminal [[Category::paper]] by Cohen is one of the finest...". The other valid category links are [[Category::method]], [[Category::problem]] and [[Category::dataset]].

If the paper makes use of some learning method or analysis method that should be described on a separate wiki page, then add a link like this one [[UsesMethod::pointwise mutual information]] or [[UsesMethod::logistic regression]]. Generally, it's best to put a learning method on a new page if it is going to be used by more than one author; otherwise, just describe it in the body of the paper page. If you create a link called [[UsesMethod::pointwise mutual information]] and the page for "pointwise mutual information" as well, make sure you mark the "pointwise mutual information" page as a dataset page, using a [[Category::dataset]] link.

There is also a semantic link for UsesDataset - which should link a paper page and a page marked as [[Category::Dataset]] - AddressesProblem - which should link a paper and a [[Category::problem]] page - and RelatedPaper - which should link two paper pages.

Don't make up new semantic tags. If you want to link a method to a (say) related method, just use a plain old hyperlink

Checking your work

To check you've done the semantic links right:

  • Look at the facts at the bottom of the page. Are they what you intended? is anything missing?
  • Look at the Special:Properties page. If you see a property that's only been used once or twice, it's probably a mistake. Track it down and fix it (if it's yours).
  • Look at the lists on the category pages, like Dataset or Problem. These are dynamically generated, so if you've added something, it should show up there.