Proj:Core/Editing Guide

From School of CS Student Wiki
Jump to: navigation, search

Introduction

This guide will explain to you the general principles to follow when editing pages that are part of the Core Project.

Structure

This wiki is intended to help students revise material as well as learn it. These two goals require that the material be carefully structured. Ideas need to be fully explained so as to aid learning, but they also need to stand alone and be easily found to aid revision.

In general, try to split up the material logically, trying not to overlap subjects. Keep the pages short and relevant to a specific topic so as not to overload a reader with information. Alternative explanations of the same topic are encouraged for the sake of helping as many students as possible. Sometimes, a different way of wording the same explanation or a different analogy can make all the difference in somebody's understanding of a topic. However, do not put two explanations on the same page. Link to alternative explanations at the end of the relevant section so a reader can choose to see them if needed without being presented with more information than necessary.

Style

Use proper English. Be mindful that international students may have trouble with slang, and poor grammar and spelling will be frustrating to people trying to learn and revise. Use a spell checker if necessary.

The writing style doesn't have to be entirely formal, feel free to inject some humour into people's lives. We'll need it by exam time. As long as you get to the point and cover the material people are expecting on the page, then things should be fine. Keep it clean though, there are a wide variety of people attending this university so be mindful of people's differing tastes.

Citations and Plagarism

Since the site is supposed to give full explanations from a student perspective, avoid following any lecture slides too closely. Make sure your work is original and follows your own understanding of the topic. It helps to avoid writing notes until you can do so without a textbook or slides in front of you.

It is very important to avoid plagiarism and to give credit to the authors of any material you use. Make use of the syntax for footnotes. If there are external resources that do a good job of explaining something, link to them instead of copying or trying to paraphrase their material. Linking resources also frees us all from the pain of maintaining a copy of something. It may often be a good idea to include a section at the bottom of each page for useful external resources.

References can be inserted as follows:

Tomato sauce can be hilarious at times.<ref>[http://youtu.be/_C3D0rcFXrY Heinz Automato 4]</ref>

Will give:


Tomato sauce can be hilarious at times.[1]


Remember to put a references section at the foot of the page:

== References ==
<references/>

Content

The content is intended to help people to do two things:

Revise for exams Understand topics they are having difficulty with during the course With this in mind, make sure the content of a page stays on topic and stands alone. When revising, people often want to find and revise specific topics so it is important to keep all the material pertaining to a particular topic well labelled and located in one place. If a page depends on other material being covered, Provide a list of dependencies which link to the relevant page. You don't need to link to all the dependencies of a page that is listed, as the reader can just follow the dependency list on that page.

When people are trying to understand a topic, it needs to stand on its own. Your explanations should make no assumptions about a person's ability or knowledge other than what is a listed dependency or knowledge that was mandatory in most schools. Start at the beginning of a topic and proceed step by step to the end.

Useful Extensions

MathJax and ASHighlight have been installed to render maths and highlight code.

To use MathJax, just use the tags and LaTeX maths environment commands:

<math>A \land B \rightarrow C</math>

Gives:



To use syntax highlighting:

<source lang=java line=1>
public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Hello World!");
  }
}
</source>

Gives:


1 public class HelloWorld {
2   public static void main(String[] args) {
3     System.out.println("Hello World!");
4   }
5 }

General Advice

  1. Make sure that all content is useful and correct. If you see anything that is blatantly incorrect, or slightly misleading, please edit the content.
  2. Write in full sentences and proper English. If you have trouble with English that's fine, but please then flag your content as needing a clean up with {{FlagBox|type=cleanup|text=The English in this page needs checking by another editor.}}
  3. Credit any sources that you use, particularly when you are rewording a source - plagiarism is massively frowned upon and will make it difficult to keep this wiki public. There's no plagiarism filter, but this is no excuse for violating copyright. If you find a good explanation for a topic on a website then it might be a good idea to give a summary of the page's contents and provide the link rather than trying to paraphrase the contents of the webpage!
  4. This includes lecture slides - if you are simply re-wording lecture slides, make sure to credit the lecturer and their slides!
  5. Try to make explanations as concise as possible. If anything is blatantly beyond the scope of a syllabus or is particularly complex, it may be a good idea to mark it as “Advanced Material” so that people can make an informed decision as to whether to read through it. Conciseness will aid during revision.
  6. Try to keep explanations for different topics on different pages. This keeps the Wiki organised and neat.
  7. Multiple explanations are okay unless one is incorrect. Sometimes, a different way of wording the same explanation or a different analogy can make all the difference in somebody's understanding of a topic. If you have a valid and different contribution to make then go ahead and make it! Just don't put two explanations for the same thing on the same page. Add an 'alternative explanation' link to the relevant section and write your explanation on another page. This helps keep pages free of unnecessary bloat, but makes it easy to find the explanation if needed.

Examples

For an example of how the module pages should be structured, take a look at Advanced Computer Graphics.

References

Authors

  • gravatar Mbax9mc3 [userbureaucrateditorsysopPHRhYmxlIGNsYXNzPSJ0d3BvcHVwIj48dHI+PHRkIGNsYXNzPSJ0d3BvcHVwLWVudHJ5dGl0bGUiPkdyb3Vwczo8L3RkPjx0ZD51c2VyPGJyIC8+YnVyZWF1Y3JhdDxiciAvPmVkaXRvcjxiciAvPnN5c29wPGJyIC8+PC90ZD48L3RyPjwvdGFibGU+]