# 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: “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.

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).
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

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

Children:

Parents:

• @2, @131, please read, since you’ll be creating most of the content. One of Jaan’s complaints was that our current content is not standardized. This is the first step in fixing that. Feel free to suggest more rules.

• Fixed, thanks.

• Should we discourage titles for the top section of a page (e.g. Group homomorphism)? I think the top section should universally be an intro paragraph, and additionally having a title on the top line causes bad-looking/​useless automatic summaries.

Edit: Confirmed on Slack and added.

• I think “universally” is too strong a word, but I agree that most of the time it’s the right thing to do. Including this page.

• True, there may be odd exceptions. And yep, fixed :)

• Note that this is an admin-only feature for now. So maybe should be left off the style guide or marked in some way so that people aren’t confused about it.

• What do you mean by this—could you say more about how it’s different from the previous reason?

• In the body: you as a personal pronoun, y/​n?

• Yes in guides and explanations, I think yes universally but pinging slack for opinions.