User blog:Kjnoren/Style Guides Should Be Guides

This is a continuation of my earlier article Write Text, Make Links, discussing how a style guide or manual of style fits into a wiki as a collaborative and ongoing venture. It is not a finished example that can be adapted to an individual wiki, rather an attempt to provide tools to reason about and evaluate a style guide, and how to decide what to include.

Note: You might see different terms used on different wikis, like Manual of Style, Style Guide, Layout Guide, or something else. I use the term style guide here, but as used here there is no real conceptual difference between the terms.

Rules versus guides
Wiki rules and style guides should both be living documents that evolve as their wiki evolves and which support each other. But they serve fundamentally different roles in the wiki. Wiki rules describe how wiki editors and admins should behave on the wiki, and how such rules are to be enforced. A style guide describes the desired state of the wiki. One is about people, the other about pages. A style guide should primarily be stated in positive terms—this is what we do or what we want to achieve—rather than in negative terms—what is disallowed.

Style guides can grow to become rather large, and by their nature might document highly technical or disparate elements. It is thus a mistake to make it a requirement for new contributors to read the entire style guide first. It is rather a reference document used by both new and old editors, meant to help them get up to speed, get things right the first time, or simply to look things up.

A style guide is explored
The primary role of the style guide is to document how things are done. However, one seldom knows the best way of doing a thing before one has actually done it. Thus the doing should be done first, and only then the documentation written based on the doing. To go the other way around likely means lots of unworkable or unneeded rules and lots of discussion going in circles.

Put another way, most “rules” in a style guide should first be tested out or be used by one or preferably several pages. Create the style guide so it fits established and workable practice on the local wiki.

Another way to look at it is that like many types of policies, the process of creating it is at least as important as the finished document. Use the opportunity to discuss and test out how the wiki should look amongst the contributors, and try to involve as many as possible in it, just as is said in the Best practices for administrators.

Standardisation
One of the real values of a style guide is to promote standards. This can include standard section headings and their order for different types of pages, or typographical standards, or when a page should be created about an object.

Most standards should be treated as soft standards. Standardised section headers should define the most common types of section headers and the order they should appear in, but there should be no requirement that all section headers be present, or that it’s not allowed to add other section headers if the content of the page calls for it. The role is rather to help new editors by giving them a standard structure to adhere to and to make linking to page fragments easier.

An especially important area to attempt to standardise, or at least provide guidelines on, is page names, redirects, disambiguations, and links. These are the elements that are widely used on a wiki and makes it function as hypertext.

Common areas of standardisation include if the wiki should use British or American English spelling, or if headlines and wiki pages should use sentence case or some form of title case.

But it’s a mistake to standardise too much or in too much detail. Rules on things like the Oxford comma, formatting details of references, or exact placement of punctuation marks will too often be a hindrance for editors, lead to needless arguing, or can be used as a tool for established contributors to gatekeep against newcomers. That doesn’t mean a style guide should never contain guidelines about details, but there should be a good reason for doing so.

If a specific formal presentation is desired, e.g. of references, it is often better to create templates for this rather than to attempt to document all the details in the style guide.

Documentation
Another important part of the style guide is that it’s a natural place to act as a hub for templates that can be found on the wiki. It can not and should not be instead of the specific per-template documentation, but it can serve as an index, give the basics of some of the more important or common ones, and act as a guide on when and how different templates are to be used.

Working out a style guide can also be an excellent time to revisit and revise the various templates of a wiki. Perhaps some templates fill similar roles but use differently named parameters, or in different order? Take the opportunity to fix this while working on the style guide.

Prescription
Even if most of the style guide is descriptive or documentary, there is still need for some prescriptive elements. However, breaking these “rules” should not be treated as breaking the actual wiki rules. Think of it more as that anything that breaks the prescriptive parts of the style guide should be fixed as soon as possible. Think of them as standardisation rather than rules.

Examples of such prescriptive elements can be a decision to use American or British spelling conventions, how section headlines should be capitalized, or some basic guidelines on what to include in references.

There is one exception that I can think of to this, and that is when a wiki needs a policy on real-life people and sources about them. Conceptually, this fits much better in the style guide than the wiki rules, since the style guide is about content and not behaviour. In this case, there should be an overriding rule—like “treat personal data with care and based on reliable sources”—and then a referral to the style guide. The style guide can contain detailed guidelines on what type of personal data is OK to include, how it is to be handled, and guidelines on what is required for a source to be considered reliable.

Good writing cannot be standardised
One thing to keep in mind is that the style guide cannot standardise good writing. It can say that good writing is desired, but there is no way to make it identify what is good writing. It is perfectly possible to write a page that fully follows all the formal requirements in the style guide while still being unreadable nonsense, as well as to write an excellent page that breaks all or most of the guidelines.

Admins and editors should thus work to establish and develop a good editorial eye rather than relying on or enforcing detailed style rules. Good pages that seemingly run counter to the style guide should be an opening to question the style guide, not to gatekeep the person writing the page.

Examples
The Filkwiki is a discography. It does not have much focus on typography, but instead has guidelines on personal data, naming pages and images, and documenting widely used templates.

The Elliott Kay Wiki is about the various books by author Elliott Kay. It is highly developed.

The H.P. Lovecraft Wiki is also a literary based wiki. It has detailed guidelines on how to mark and discern information from various sources and origin, as well as about images.

The Zack Snyder Wiki documents various works by filmmaker Zack Snyder. Like the filkwiki it makes use of preload templates, and also uses exemplar pages as positive examples on how to create articles rather than formal rules.

The Final Fantasy Wiki is a large wiki with a style guide focused on names and editorial judgment.