Article format guidelines

From Sagataflwiki

(Difference between revisions)

Latest revision as of 16:54, 4 February 2011

These are the guidelines for what an article about Sagatafl should be like. They are very good, but they are not perfect, so you don't have to follow them 100% all of the time

Note that this article seems to be a mixture of defining what an article should be like, and coverage of what-you-can-do-to-help information, which is unfortunate; they're two different things, belonging each to their own article or set of articles.

Introduction

Any article meant for general reading, meaning an article that is not a Talk/Discussion page, a userpage/bio, or an article that talks about what the SagataflWiki should be like and how it should function and be edited, should adhere to the following guidelines:

First a short introduction describing what the article is about. This empowers the reader to skip the article if it contains nothing that is of immediate interest to him, typically options or rules that are irrelevant to his current pursuits. This should be one sentence, maybe two, rarely three, never more than three (unless it is necessary).
A table of contents (ToC). This is automatically omitted in articles with too few Section dividers, and should only rarely be inserted into such articles with a forced tag, command, magic word, or whatever it is called.
Articles should usually be divided into sections, using the three section levels: level two, level three and level four.
1. An article that is very short does not need sections. A slightly longer article needs level two section-dividers (two equal signs before and after the header words), and a slightly longer article again should probably make use of level three dividers (three equal signs), and a long article should also use level four dividers (four equal signs).
2. If you think an article needs a table of contents (ToC), and it doesn't already have one, then either divide it into some more sections, so that the wiki software automatically inserts the ToC (this is almost always the best solution), or else there is a command that forces the wiki software to insert a ToC.
At the bottom of the article there should often be a list of See Also-type internal links to other articles pertinent to the subject matter. This is in addition to tags (see further down). This list sometimes needs to be short, other times it needs to be rather long. In some cases you may want to split the list up with level four dividers.
After the article are category tags. This is one place where it is easy to contribute; if you think the article is missing one or two tags, add them. It is very easy. (INSERT LINK to doc explaining how to add categories).

Categories can perform various functions, but basically they're about making it easier to find stuff, especially stuff that is in some way related to the current article.

Character creation has to do with spending DP, PPs and SPs, not creating magic items or choosing mundane gear with traits, not other kinds of magical choices that the character can make; note the distinction: choices that have to do with magic which the player gets to make are character creation choices.

Categories can also be intended to be temporary, for instance "grammar" or "proof" indicate, respectively, that the article needs to be worked over by someone who has a good understanding of English grammar or English spelling. "ukify" means that the article is deemed to contain too many US-style spellings, contrary to the intended style which is British English, also called UK English.

You can ADD these tags, if you think an article has enough problems to warrant it, and you can also search for these tags if you feel qualified to FIX such errors yourself. If you think you've fixed all the errors, just remove the tag from the article. Someone will add it again if they think your fixes have been inadequate.

Tags may also be created to indicate that an article is incoherent, difficult to understand (for the target audience), written in a style inconsistent with the rest of the articles in this wiki, or contains rules that are easy to misunderstand, i.e. interpret in more than one way.

Internal links

This is another area where you can easily HELP. Turn words into internal links. Turn lots of words into internal links. Turn metric assloads of words into internal links! The faster the reader can navigate from article to article, the better. Some wikis have, or seem to have, a policy that any given word should only be made into a link the first time it appears in an article.

This is not the case here. If a word appears twice in the same sentence, only one instance of it (and almost always the first instance, unless you think you have a good reason) should be made into a link. If a word appears twice in the same paragraph, it should probably only be made into a link once.

If a word appears several times in an article, each instance of that word that is likely to be the only one visible at any specific scroll-position should be made a link, so that if the reader wishes, he can click it immediately, instead of having to scroll up or down to find a clickable version of that word.

Also do not link extremely obvious terms like RD and attribute, except the first time those words appear in articles that specifically deal with RDs or attributes, typically item Enchantments that can lower RDs or otherwise affect RDs, or item Enchantments that can give bonuses to attributes.

External links

Be careful of these. We can't control what's elsewhere on the web. Even if you find a web page that looks nice and full of useful content, it may change next week into nasty propaganda for some cause of wrongness. Be particularly careful about articles in other wikis, such as English Wikipedia, that deals with human variety, e.g. measurable and important differences between individuals, sexes or racial groups. Articles on such controversial subjects can change without warning, going from fact to politically correct truthiness, or the other way around. If you feel something is truly important, link to a static version of that text and on the article's Discussion page rather than within the article itself.

Exceptions are links to articles explaining how to use MediaWiki, and articles on English usage (grammer, spelling, syntax) that you think may be helpful to some of the editors (if you think such material is only useful to non-editor readers, do not add it). Links to such material is welcome.

Implement changes from To-Do lists

One of the things that the Talk page for an article may contain, is a To-Do list, of various changes and improvements that should be made. If you are certain that you know the meaning of some of the items on such a list, you may implement those changes, ignoring those you are unsure about. Be sure to leave some kind of mark or note on the Talk page, listing or at least mentioning each of the changes from the To-Do list that you've made, and state it clearly if there are some of those changes that you are slightly uncertain about.

Diagrams

Any diagrams that can help the reader understand aspects of Sagatafl are more than welcome, so if you can make them, they'll be received with gratitude. If you want to make colour diagrams, stick to basic colours (a palette of the 16 or 32 most common colours perhaps, and ideally only the 8 basic RGB colour combinations) and if at all possible also make a grey-scale version of your diagram for users without colour displays. Keep in mind, not everyone who reads this wiki will be using a mexapixel-resolution computer screen. We can't know what devices people will use for browsing the web, even in the near future.

Tables

Tables are good. Tables help to give the reader a fast and clear overview of what options are available to him, e.g. during character creation, item Enchantment, the crafting of mundane items of high quality, purchasing equipment, or using character abilities.

Depending on how much functionality MediaWiki actually has, some kind of method to compare tables would be great, but in most cases there is no need to add sorting-buttons to tables; they rarely contain the kind of information that the reader would want to sort according to different columns.

Helping people learn Sagatafl

Some of the documents in this wiki are not rules, but rather attempt to teach Sagatafl in various ways, such as fairly detailed contrast-and-compares with other RPG systems that are either very popular or else have notable similarities with Sagatafl.

Writing game table aids

This is another thing. Creating tables, in PDF format, intended to be printed out and referenced during play.

Technical help

CSS

If you know CSS, there's a lot you can do to help, such as making the layout more stylish, and easier to read, maybe also easier to use.

Mediawiki expertise

Likewise,if you actually know how to use MediaWiki, better than the Designer does, which is not too unlikely, there is also a lot you can do.

MS Excel

If you have expertise in the Microsoft Excel spreadsheet, then you can possibly help with working on the character creation assistance spreadsheet, in various ways. Note, though, that this project won't be started soon. If you do know Excel fairly well, you may request to see the old spreadsheet, for study purposes, but note that a new one is to be created from scratch, using slightly more clever principles.

OO Calc

xxx

Online Excel

xxx

Other computerized character creation assistance

If you are willing to contribute a lot of work, you may start on a non MS-Excel...

Illegal content

Don't add any. Anything that is copyrighted, or anything that is otherwise illegal to distribute, such as classified government or military information.

You're smarter than you think

Well, it's not guaranteed, but changes are you are. If you think there should be a category tag added, or that a word should be linked, you are more likely to be CORRECT than to be wrong. So do it. You're helping.

If you dislike a rule

Don't change it. Instead, either write about it on the Discussion page, explainnig why you dislike it and how you'd like tos ee it changes, or else contact the Designer privately (usually email, sometimes mailing list or MSN, or face-to-face) and raise the issue. If you can convince the Designer, he will either give you permission to implement the change yourself, or else do it on his own.

Ownership

Everything you write or do within this wiki becomes the ownership of the Designer. Do not contribute if you do not accept this. Also you cannot withdraw your contributions once made.

@@ Line 1: / Line 1: @@
-Any article meant for general reading, meaning an article that is not a Talk/Discussion page, a userpage/bio, or an article that talks about what the SagataflWiki should be like and how it should function and be edited, should adhere to the following guidelines:
+These are the guidelines for what an article about Sagatafl should be like. They ''are'' very good, but they are not perfect, so you don't have to follow them 100% all of the time
-. First a short introduction describing what the article is about. This empowers the reader to skip the article if it contains nothing that is of immediate interest to him, typically options or rules that are irrelevant to his current pursuits. This should be one sentence, maybe two, rarely three, never more than three (unless it is necessary).
+Note that this article seems to be a mixture of defining what an article should be like, and coverage of what-you-can-do-to-help information, which is unfortunate; they're two different things, belonging each to their own article or set of articles.
-. A table of contents. This is automatically omitted in articles with too few Section dividers, and should only rarely be inserted into such articles with a forced tag, command, magic word, or whatever it is called.
+== Introduction ==
+Any article meant for general reading, meaning an article that is not a Talk/Discussion page, a userpage/bio, or an article that talks about what the SagataflWiki should be like and how it should function and be edited, should adhere to the following guidelines:
-. Articles should be divided into sections, using the three section levels: level two, level 3 and level 4. The longer an article is, the more sections it should have. If you think an article needs a table of contents, and it doesn't already have one, divide it into some more sections. This makes the article more accessible, and automatically causes the wiki software to insert a table of contents.
-. At the bottom of the article there should often be a short (sometimes not so short) list of See Also-type links to other articles pertinent to the subject matter. This is in addition to tags (see further down).
+# First a short introduction describing what the article is about. This empowers the reader to skip the article if it contains nothing that is of immediate interest to him, typically options or rules that are irrelevant to his current pursuits. This should be one sentence, maybe two, rarely three, never more than three (unless it is necessary).
+# A table of contents (ToC). This is automatically omitted in articles with too few Section dividers, and should only rarely be inserted into such articles with a forced tag, command, magic word, or whatever it is called.
-. After the article are category tags. This is one place where it is easy to contribute; if you think the article is missing one or two tags, add them. It is very easy. (INSERT LINK to doc explaining how to add categories).
+# Articles should usually be divided into sections, using the three section levels: level two, level three and level four.
+##An article that is very short does not need sections. A slightly longer article needs level two section-dividers (two equal signs before and after the header words), and a slightly longer article again should probably make use of level three dividers (three equal signs), and a long article should also use level four dividers (four equal signs).
+##If you think an article needs a table of contents (ToC), and it doesn't already have one, then either divide it into some more sections, so that the wiki software automatically inserts the ToC (this is almost always the best solution), or else there is a command that forces the wiki software to insert a ToC.
+# At the bottom of the article there should often be a list of See Also-type internal links to other articles pertinent to the subject matter. This is in addition to tags (see further down). This list sometimes needs to be short, other times it needs to be rather long. In some cases you may want to split the list up with level four dividers.
+# After the article are category tags. This is one place where it is easy to contribute; if you think the article is missing one or two tags, add them. It is very easy. (INSERT LINK to doc explaining how to add categories).
 Categories can perform various functions, but basically they're about making it easier to find stuff, especially stuff that is in some way related to the current article.
-Character creation has to do with spending AP, PPs and SPs, not creating magic items or choosing mundane gear with traits, not other kinds of magical choices that the character can make; note the distinction: choices that have to do with magic which the player gets to make are character creation choices.
+Character creation has to do with spending DP, PPs and SPs, not creating magic items or choosing mundane gear with traits, not other kinds of magical choices that the character can make; note the distinction: choices that have to do with magic which the player gets to make are character creation choices.
 Categories can also be intended to be temporary, for instance "grammar" or "proof" indicate, respectively, that the article needs to be worked over by someone who has a good understanding of English grammar or English spelling. "ukify" means that the article is deemed to contain too many US-style spellings, contrary to the intended style which is British English, also called UK English.
@@ Line 21: / Line 24: @@
 Tags may also be created to indicate that an article is incoherent, difficult to understand (for the target audience), written in a style inconsistent with the rest of the articles in this wiki, or contains rules that are easy to misunderstand, i.e. interpret in more than one way.
-Internal links
+== Internal links ==
---------------
 This is another area where you can easily HELP. Turn words into internal links. Turn lots of words into internal links. Turn metric assloads of words into internal links! The faster the reader can navigate from article to article, the better. Some wikis have, or seem to have, a policy that any given word should only be made into a link the first time it appears in an article.
@@ Line 28: / Line 30: @@
 If a word appears several times in an article, each instance of that word that is likely to be the only one visible at any specific scroll-position should be made a link, so that if the reader wishes, he can click it immediately, instead of having to scroll up or down to find a clickable version of that word.
-Do not link word that are common in the English language.
 Also do not link extremely obvious terms like RD and attribute, except the first time those words appear in articles that specifically deal with RDs or attributes, typically item Enchantments that can lower RDs or otherwise affect RDs, or item Enchantments that can give bonuses to attributes.
-See also
+== See also ==
---------
 Instead of turning in-article words into internal links, you may sometimes feel like putting those words in as stand-alone links at the bottom of the article, in the See Also section.
-External links
+== External links ==
---------------
 Be careful of these. We can't control what's elsewhere on the web. Even if you find a web page that looks nice and full of useful content, it may change next week into nasty propaganda for some cause of wrongness. Be particularly careful about articles in other wikis, such as English Wikipedia, that deals with human variety, e.g. measurable and important differences between individuals, sexes or racial groups. Articles on such controversial subjects can change without warning, going from fact to politically correct truthiness, or the other way around. If you feel something is truly important, link to a static version of that text and on the article's Discussion page rather than within the article itself.
 Exceptions are links to articles explaining how to use MediaWiki, and articles on English usage (grammer, spelling, syntax) that you think may be helpful to some of the editors (if you think such material is only useful to non-editor readers, do not add it). Links to such material is welcome.
-Images
+== Implement changes from To-Do lists ==
-------
+One of the things that the Talk page for an article may contain, is a To-Do list, of various changes and improvements that should be made. If you are certain that you know the meaning of some of the items on such a list, you may implement those changes, ignoring those you are unsure about. Be sure to leave some kind of mark or note on the Talk page, listing or at least mentioning each of the changes from the To-Do list that you've made, and state it clearly if there are some of those changes that you are slightly uncertain about.
-This wiki is intended to be
-Diagrams
+== Diagrams ==
---------
 Any diagrams that can help the reader understand aspects of Sagatafl are more than welcome, so if you can make them, they'll be received with gratitude. If you want to make colour diagrams, stick to basic colours (a palette of the 16 or 32 most common colours perhaps, and ideally only the 8 basic RGB colour combinations) and if at all possible also make a grey-scale version of your diagram for users without colour displays. Keep in mind, not everyone who reads this wiki will be using a mexapixel-resolution computer screen. We can't know what devices people will use for browsing the web, even in the near future.
-Tables
+== Tables ==
-------
 Tables are good. Tables help to give the reader a fast and clear overview of what options are available to him, e.g. during character creation, item Enchantment, the crafting of mundane items of high quality, purchasing equipment, or using character abilities.
 Depending on how much functionality MediaWiki actually has, some kind of method to compare tables would be great, but in most cases there is no need to add sorting-buttons to tables; they rarely contain the kind of information that the reader would want to sort according to different columns.
-Illegal content
+== Helping people learn Sagatafl ==
----------------
+Some of the documents in this wiki are not rules, but rather attempt to teach Sagatafl in various ways, such as fairly detailed contrast-and-compares with other RPG systems that are either very popular or else have notable similarities with Sagatafl.
-Don't add any.
-You're smarter than you think
+== Writing game table aids ==
------------------------------
+This is another thing. Creating tables, in PDF format, intended to be printed out and referenced during play.
+== Technical help ==
+=== CSS ===
+If you know CSS, there's a lot you can do to help, such as making the layout more stylish, and easier to read, maybe also easier to use.
+=== Mediawiki expertise ===
+Likewise,if you actually know how to use MediaWiki, better than the Designer does, which is not too unlikely, there is also a lot you can do.
+=== MS Excel ===
+If you have expertise in the Microsoft Excel spreadsheet, then you can possibly help with working on the character creation assistance spreadsheet, in various ways. Note, though, that this project won't be started soon. If you do know Excel fairly well, you may request to see the old spreadsheet, for study purposes, but note that a new one is to be created from scratch, using slightly more clever principles.
+=== OO Calc ===
+xxx
+=== Online Excel ===
+xxx
+=== Other computerized character creation assistance ===
+If you are willing to contribute a lot of work, you may start on a non MS-Excel...
+== Illegal content ==
+Don't add any. Anything that is copyrighted, or anything that is otherwise illegal to distribute, such as classified government or military information.
+== You're smarter than you think ==
 Well, it's not guaranteed, but changes are you are. If you think there should be a category tag added, or that a word should be linked, you are more likely to be CORRECT than to be wrong. So do it. You're helping.
-If you dislike a rule
+== If you dislike a rule ==
----------------------
 Don't change it. Instead, either write about it on the Discussion page, explainnig why you dislike it and how you'd like tos ee it changes, or else contact the Designer privately (usually email, sometimes mailing list or MSN, or face-to-face) and raise the issue. If you can convince the Designer, he will either give you permission to implement the change yourself, or else do it on his own.
-Ownership
+== Ownership ==
----------
+Everything you write or do within this wiki becomes the ownership of the Designer. Do not contribute if you do not accept this. Also you cannot withdraw your contributions once made.
-Everything you write or do within this wiki becomes the ownership of the Designer. Do not contribute if you do not accept this. Also you cannot withdraw your contributions.
+[[Category:Editor stuff]]
+[[Category:Editor guidelines]]
+== See also ==
+[[Article]] to see what the basic article structure should look like and<br>
+[[Article in wikitext]] from where you can copy-n-paste the wikitext straight into a newly created article to get most of that structure.