Difference between revisions of "Tips for writing wiki pages"
| (10 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| + | These are tips for students in [[Social Media Analysis 10-802 in Spring 2011]]. | ||
| + | |||
== Before you start == | == Before you start == | ||
Look at some [[Turney,_ACL_2002|example]] [[Pang_et_al_EMNLP_2002|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. | Look at some [[Turney,_ACL_2002|example]] [[Pang_et_al_EMNLP_2002|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 == | == Naming your page == | ||
| Line 11: | Line 23: | ||
== Semantic links == | == Semantic links == | ||
| − | If the page describes a paper, include a link of the form <nowiki>[[Category::paper]]</nowiki>, like this: "This seminal <nowiki>[[Category::paper]]</nowiki> by Cohen is one of the finest...". The other valid category links are <nowiki>[[Category::method]]</nowiki> and <nowiki>[[Category::dataset]]</nowiki>. | + | === The short story === |
| + | |||
| + | In brief, the named links you should be using are: | ||
| + | * [[Property:Category|Category]] links a new page to one of the special pages [[paper]], [[method]], [[dataset]], or [[problem]]. | ||
| + | * [[Property:UsesMethod|UsesMethod]] links a [[paper]] page to a [[method]] page. | ||
| + | * [[Property:UsesDataset|UsesDataset]] links a [[paper]] page to a [[dataset]] page. | ||
| + | * [[Property:AddressesProblem|AddressesProblem]] links a [[paper]] page to a [[problem]]. | ||
| + | * [[Property:RelatedPaper|RelatedPaper]] links a [[paper]] to another [[paper]]. | ||
| + | |||
| + | === The longer story === | ||
| + | |||
| + | In not-so brief: If the page describes a paper, include a link of the form <nowiki>[[Category::paper]]</nowiki>, like this: "This seminal <nowiki>[[Category::paper]]</nowiki> by Cohen is one of the finest...". The other valid category links are <nowiki>[[Category::method]]</nowiki>, <nowiki>[[Category::problem]]</nowiki> and <nowiki>[[Category::dataset]]</nowiki>. | ||
| + | |||
| + | 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 <nowiki>[[UsesMethod::pointwise mutual information]]</nowiki> or <nowiki>[[UsesMethod::logistic regression]]</nowiki>. 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 <nowiki>[[UsesMethod::pointwise mutual information]]</nowiki> and the page for "pointwise mutual information" as well, make sure you mark the "pointwise mutual information" page as a dataset page, using a <nowiki>[[Category::dataset]]</nowiki> link. | ||
| + | |||
| + | There is also a semantic link for UsesDataset - which should link a paper page and a page marked as <nowiki>[[Category::Dataset]]</nowiki> - AddressesProblem - which should link a paper and a <nowiki>[[Category::problem]]</nowiki> 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 semantic links === | ||
| − | + | 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. | ||
Latest revision as of 18:00, 1 February 2011
These are tips for students in Social Media Analysis 10-802 in Spring 2011.
Contents
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
The short story
In brief, the named links you should be using are:
- Category links a new page to one of the special pages paper, method, dataset, or problem.
- UsesMethod links a paper page to a method page.
- UsesDataset links a paper page to a dataset page.
- AddressesProblem links a paper page to a problem.
- RelatedPaper links a paper to another paper.
The longer story
In not-so brief: 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 semantic links
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.
