Style guidelines

Having consistency across pages improves user experience and makes Arbital pages feel more polished. This page lists guidelines to follow when writing a page’s title, clickbait, summary, and body text.

If there are any stylistic considerations you’d like clarified, comment here.

For style guidelines that apply specifically to the math domain, see math style guidelines.

Global

Yes: US spelling and terminology noteOne day we’ll have localization..

Title

Yes: “First letter is capital”
Yes: “Is it okay for the title to be a question?”
Yes: “Short and sweet”
No: “Capitalize Every Word”
No: “**Markdown**”
No: “Period at the end.”
No: “This is a long title that’s basically a complete sentence of its own” (Use clickbait for that)

• Exceptions: asking a question or evaluating a proposition

Clickbait

Yes: “First letter is capital.”
Yes: “Pique user’s interest in the topic.”
Yes: “Most clickbaits are just one sentence telling user what they might find out if they read the page.”
Yes: “Can a clickbait ask the reader a leading question?”
Yes: “Period or other punctuation at the end.”
Yes: Omitting clickbait if the title is descriptive enough.
No: “Capitalize Every Word”
No: “**Markdown**”

Alias

• Yes: “lowercasewithunderscores”

• Yes: “usingfullwords”

• Yes: “bespecificstyle_guide” (as opposed to “specific”)

• No: “abrv” (abbreviations)

• No: “MUAs” (made up acronyms)

• No: “aliasthatisclearlywaytoolongtobeusefulor_memorable”

• If the alias has alternate meanings, e.g. “element”, append the relevant domain’s name, e.g. “elementmathematics” (or, for arbital domain pages, prepend e.g. “arbitalstyle_guideline”).

• Prefer single (“penguin”) to plural version (“penguins”), if possible.

Text body

Summary

Yes: Put it at the top of the page
Yes: Not having a summary if the first paragraph is already a good summary. Yes: “Paragraph long explanation summarizing the contents of the page…”
Yes: “Using Markdown as normal.”
Yes: “If the page has a vote, describe exactly what the vote is about.”

Body

Yes: Conversational, fun tone.
Yes: We as a personal pronoun.
Yes: Explaining things in whatever way works best.
No: I as a personal pronoun.

Length

Most Arbital pages are between one to five screens long. They are usually much shorter than Wikipedia pages. It’s probably best to break very long pages into a few shorter pages, especially if they need to be used as requisites.

Links

Yes: Using a link when a concept is introduced or mentioned within a section.
Yes: Using a red link when you want to indicate that there should be a page for that concept (with or without a title, i.e. display text vs display text).
Yes: Link glossary pages for overloaded words.
No: “Using the link in very close proximity to the link.”
No: Specifying the title of the page exactly: Style guidelines, instead just do Style guidelines

Headers

Yes: Capitalize first letter and no period at the end
No: Header for the opening section
No: “Period or other punctuation at the end.”