Wikipedia:Style of policy and guideline pages

From Wikipedia, the free encyclopedia

✘ This Wikipedia page is currently inactive and is retained as a historical archive.
A historical page is either no longer relevant or consensus has become unclear. If you want to revive discussion regarding the subject, you should seek broader input via a forum such as the proposals page of the village pump.
This page in a nutshell: Policies and guidelines are written in a clear, consistent way so editors can understand, follow, and enforce them with a minimum of dispute

This page is to help editors write clear, concise, effective policy and guideline pages. be bold when copy editing these pages for style and format, but careful to preserve the substance of those pages. If this page conflicts with any other, the other necessarily prevails. It is not meant to change any rules on Wikipedia, only to make those rules easier to understand.

Contents

[edit] Rationale

Wikipedia works best when its policy and guideline pages are accessible, unambiguous, and understandable by all. These pages grow longer over time, accumulating material put in for many different reasons by different editors. Yet not every good Wikipedian is a strong copyeditor, not even the people who write policy and guideline pages. This page is to help all editors keep the pages clear and succinct when writing a new page, adding to an existing page, and periodically cleaning up pages that have accumulated stylistic weaknesses over time.

[edit] Style for policy and guideline pages

[edit] Include these components

Include the following, in order. Deviation is okay within reason in the interest of clarity and usability.

  1. Name. A short, neutral name that clearly communicates the scope of the policy or guideline. See WP:NAME
  2. Header box. A template to say what kind of policy or guideline it is. See: Wikipedia:Shortcuts .
  3. Nutshell. A phrase or sentence on the scope or purpose of the policy (encouraged). Use {{policy in a nutshell | <explanation>}} for policies and {{guideline in a nutshell | <explanation>}} for guidelines.
  4. Summary A few sentences on what the policy is, what it applies to, and how it fits in with other policies. (encouraged)
  5. Sidebar box. Template to list various related policies, e.g. {{template:policylist}}, {{template:Guideline list}}, {{[[template:Style]]}}, etc. (optional).
  6. Rationale. A few paragraphs on the need for the policy, the problems it seeks to avoid, the benefits it serves, how it addresses the needs or policies, the history, context inside or outside of Wikipedia etc. (encouraged if there is no summary).
  7. Rules. The main section. If there are many, consider breaking them up by subject matter, by type (content, style, procedural, behavioral), by effectiveness (i.e. requirements, prohibitions, options, etc.), or into sub-rules.
  8. Examples. Links, descriptions, or hypotheticals (optional). If there are many, consider breaking down by subject, or by examples of compliance versus violation.
    • Case-in-point examples may be very specific, for purposes of illustration and instruction, e.g. a Bolivian unicyclist.
    • Category or fence-making examples should be phrased as broadly as possible so they can let people know the boundaries of the policy's application, and the full range within, e.g. riders of self-propelled vehicles. (optional)
  9. Enforcement. How is the policy is enforced, by what means, by whom, and what happens if tehre is a violation? Be clear on what part of this section is meant to establish a rule, versus what parts merely describe rules stated elsewhere (optional).
  10. Notes. Extended discussion of issues related to the policy. (optional)
  11. See also. Wikilinks to other policies, guidelines, or key words or concepts discussed on the page. (optional)
  12. Categories. Include appropriate categories for the page. Common categories include[[Category:Wikipedia official policy]], [[Category:Wikipedia guidelines]], [[Category:Wikipedia style guidelines]], [[Category:Copyright]], [[Category:Wikipedia how-to]], [[Category:Wikipedia editing guidelines]], etc.
  13. Principles. Insert {{Template:Wikipedia principles}} as a footer message. (encouraged)
  14. Edits to other pages. Add new pages to Wikipedia:List of policies or Wikipedia:List of guidelines. Update sidebar box templates (see above).

[edit] Rules to follow

  1. Clarity.
    • Specify type of rule. Is it a content, style, procedural, or other type of rule?
    • Strength of rule. Is the item the rule describes mandatory, encouraged, optional, discouraged, prohibited, conditional (applies only under certain conditions) and/or discretionary (editors may make their own decisions but must consider certain criteria)?
    • Make amendments explicit. If the rule overturns an earlier rule, version, consensus, or usage on a subject, make clear whether that is intentional or not. Say whether the rule is an attempt to change common understanding or behavior on a subject, or merely an attempt to reflect consensus about it.
    • Explanations and examples should be short, minimally used, and clearly identified as such if used inline with rules or other sections. If longer, consider putting them in their own section.
  2. Context. Add the following to the summary, rationale, or notes section.
    • Authority Say where the rules came from and on what authority they are made.
    • Boundaries and scope. Say where the current page end and other guidelines or policies start. In cases where there is a conflict, which page is primary?
  3. Good Format
    • Lists. Putting rules in list format is strongly encouraged. Use bullet points (*) or automatic numberings (#) for primary items, and an indent mark (:) for sub-list items. Each list item may have a brief header in '''bold'''. Whatever format you choose, be consistent throughout the page.
    • Headers. Use ==<First-level headers>== to identify the major prose components identified above. Use ===<Second-level headers>=== for organization and readability within each section.
    • Italics. Use '''italics''' for examples, "see also" references, and links to main articles that are used in-line rather than in their own proper section. Disambiguation and other similar links should also be offset and in italics.
    • Endorse other policy and guideline pages by a brief mention, link, and statement of why they matter here, rather than restating them, so as not to cause a fork or confusion over where the policy comes from. Consider a transclusion rather than cut-and-paste if quoting long policy sections verbatim.
    • Discuss images by linking, not inclusion. Use [[:Image:<imagename>]]
    • Discuss templates by linking, not transclusion. Use [[Template:<templatename>]]</nowiki>
    • Discuss categories like this: [[[[:Category:<category name>]]]]
    • Reference mark-up or other unprintable characters like this: <nowiki><text that includes markup characters></nowiki>.
  4. Good English.
    • The Manual of Style applies unless otherwise indicated here
    • Brevity. Be as short and direct as possible. Try to keep policy and guideline pages to 20K at most, and avoid undue detail or essay-like explanations.
    • Plain English is best but not to the point of degrading the meaning. Terms of art are appropriate when necessary to make a relevant point.
    • Verb tenses should be consistent throughout the article. Choose one (e.g. imperative, passive voice, etc.) and stick to it.

[edit] Things to avoid

  1. Ineffective rules. Do not add rules that are moot or unenforceable.
  2. Weak rules. Avoid rules expressed as conditional statements if there is no condition, weak modal verbs if there it is a mandatory rule, and rules of limited applicability to the subject at hand.
  3. Weak language. Avoid wikispeak, legalese, and terms of art, unless necessary to clearly convey a rule. Do not nullify rules with wishy-washy language. Avoid mixing rules and rationales in the same section, and unnecessary self-reference.
  4. Redundancy. Avoid saying the same thing twice in one page, even if phrased differently. Also avoid rules that duplicate the effect of other rules, saying the same thing in both positive and the negative, laying out a class of things as a general principle than enumerating the individual items partly or fully, and repeating rules and descriptive text from other policy or guideline pages.
  5. Mark-up. Do not use special mark-up formats (bold, italic, underline, colors, boxes, etc) merely to emphasize a statement. Avoid sideline boxes.
  6. Inappropriate content
    • Non-free images. Not appropriate on policy pages.
    • FAQ sections. These are the policy equivalent of trivia. Integrate these into the policies and examples.
    • Humor. A cute picture or quotation, used thoughtfully, is a spoon full of sugar that makes a hard rule easier to swallow. But you may not be as funny as you think you are, and too much humor is just noise.
    • Links to objectionable content. Linking to examples of copyright infringement and other illegal content is strictly prohibited. Linking to examples of poor writing, bad articles, behavior disputes, off-color jokes, racism, sexism, political or religious debates, etc., may cause more harm than good.
    • Disambiguation sections and links, except vis-a-vis other policies and guidelines. People rarely reach a policy page by accident.
    • Links that are part of a heading
    • External links, except in an eternal link section.
  7. Unnecessary sections
    • How to sections, hints, tips, and the like, except in the case of how-to guidelines. Everywhere else they just add clutter. Consider moving these to a sub-page, tutorial, or help page, and linking to them in the page.
    • Examples, except in the "examples" section. They kill the flow, are often misunderstood as rules, and rarely add much.
    • Meta-issues. Unless there is a special reason to tell people to be bold, operate by consensus, avoid incivility, and so on, do not clutter up the page with these snowball clauses. Likewise, no need to tell people what a policy is, how to interpret policies, what an encyclopedia is for, etc.
    • Wikilinks to the main space. Rule and guideline pages are not encyclopedia articles. If it is a commonly understood thing the link is unnecessary. If it is a specialized word a link may be helpful, but be mindful of the preference for plain English, and the possibility that main space pages change over time.
    • References and citations. Verifiability and reliable sources, the main reason to use citations, are not relevant to rules and guidelines.
    • Sidebars other than standard ones. They clutter things up.
  8. Shortcuts, especially to sub-sections. Use judiciously because if you add one it will be there forever because as people start linking to it.
  9. External authority. Avoid quoting rules from outside of Wikipedia policy and guideline articles, except to endorse that they apply here.

[edit] Examples

Here are some examples of things to avoid.

  1. Ineffective rules.
    • "Ghosts and rodents may not edit their own Wikipedia article" - Moot point. It never happens so it adds nothing to make a rule about it.
    • "Do not commit a felony in the course of editing an article" - Moot point. We can't do anything about it, the rule is meaningless.
    • "Do not edit while intoxicated" - Unenforceable. We cannot know who is intoxicated or not.
  2. Weak rules.
    • "Guideline pages for geese should avoid harsh consonants that frighten the animals" - limited applicability. Consider moving this to an example, sub-page, or a guideline on geese.
    • "Editors might want to consider whether it is the best idea to use sarcasm because their words could be taken the wrong way" - conditionals. Say it straight if it is a rule (e.g. "Editors must avoid language that is subject to being misconstrued"), move it to the commentary section, or else omit it entirely if it is just a complaint.
    • "Linking to foreign language sites is strictly prohibited"' - Saying never. There are exceptions to most any rule.
  3. Weak language
    • "Participants should avoid wikilawyering" - Wikispeak. Use common English words instead of words that have no application outside of Wikipedia, e.g., "Avoid rhetorical arguments." Contrast with: "Avoid transclusion", which is okay because it has no simple English equivalent.
    • "Contributions to talk pages have a presumption of good-faith, which may be rebutted by a showing of deceptive intent" - Legalese. Better to say: assume good faith of talk page contributions.
    • "Administrators should avoid ipso facto reasoning in making policy interpretations" - Term of art. Use plain English. E.g., do not assume the facts speak for themselves.
    • "Avoiding conflicts of interest is usually best." - wishy-washy language. Does the rule ban conflicts of interest or not? IF yes, say so; if no, forget the rule and add it to the rationale or comments section.
    • "It is a violation of Wikipedia policy to do X"' - self-reference to Wikipedia. Simply say "Do not do X".
    • "X causes unnecessary disruption and is therefore prohibited" - mixing rationale with rule. Simply say "X is prohibited".
  4. Redundancy
    • "Only dogs are allowed. All other animals are forbidden." - saying in both positive and negative
    • "Authors, including novelists, commentators, and all other writers...." - Redundant 'full enumeration.
    • "All authors, both living and dead, should use this template" - Redundant full enumeration
    • "All authors, including American authors, fall under this policy" - Redundant partial enumeration.
    • "American authors and all other authors..."' - Redundant partial enumeration.
    • "All articles about authors must rely on reliable, third-party published sources"' - repeats other policy page (in this case, an incomplete and therefore contradictory reference to Wikipedia's Verifiability policy).

[edit] Enforcement

Editors familiar with Wikiepdia policy should feel free to improve policy and guideline pages. No consensus is necessary to make stylistic improvements, or to revert bad edits. However, it is best to go slow at first, editing one sentence or section at a time to see if changes are accepted, before moving on to the next.

When changing a policy or guideline page, use a single edit for each rule, sentence, paragraph, etc., being changed, and an edit summary briefly mentioning that it is a stylistic change not intended to affect the rules. That way people who disagree with a particular change may revert that instead of the entire clean-up. For all but the most minor clean-ups, leave a note on the talk page explaining the change.

Be careful about particularly sensitive or contentious sections and consider making proposals in the talk page first; the exact wording in those sections may be the subject of a delicate compromise among concerned editors. If your changes are rejected do not edit war over them. Stylistic improvements should be uncontroversial.

[edit] Notes

This guideline is not about the substance of any page. A good copy-edit will not change a policy or guideline page except to make it more effective. Therefore, editors should be careful when copyediting a policy or guideline page that they do not change the meaning. When proposing new substantive policy, it is always a good idea to write in proper style even if the old policy is poorly written. However, it is sometimes a mistake to propose both substantive and stylistic changes at the same time, because that mixes changes that are supposed to be noncontroversial with changes that may be controversial. That could make underlying policy changes appear more widespread than they really are, and lead to unnecessary dispute over them. Consider making two passes: first, agree on policy, then only after the policy on a page is stable, consider cleaning up the writing on that page.

Style edits can help combat rule creep, eliminating parts of pages that are redundant, contradictory, or unnecessary.

This page is emphatically not about the process by which consensus is reached and pages are written. It is also not about what the policy and guideline pages should say, only how they say it. Other than the brief "enforcement" section it offers no guidance about how to go about and gather support for stylistic improvements. The best advice is only make improvements that will not generate legitimate controversy.

A special caution about external authority. Wikipedia policies and guidelines stem from the Five Pillars and from the policies we have all agreed to adopt. Outside laws, rules, orders, and quotations (even those of Jimbo Wales) are not binding here unless we agree to incorporate them. Quoting them here gives them the false appearance of authority. Further, pages within Wikipedia such as WikiProjects, essays, templates, help pages, tutorials, and ARBCOM opinions, are not binding rules and were arrived at in most cases without consensus that they would apply in the future across Wikipedia. Be careful about quoting or citing them so as not to give them undue weight or a false implication that they are policy.

[edit] See also