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 %%note: One 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."
[comment: 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. [page\_title display text]
vs [ display text]
).
Yes: Link glossary pages for overloaded words.
No: "Using the [same link]
in very close proximity to the [same link]
."
No: Specifying the title of the page exactly: <a href="arbital_style_guide.html">Style guidelines</a>
, instead just do <a href="arbital_style_guide.html">Style guidelines</a>
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."
Comments
Alexei Andreev
Eliezer Yudkowsky, Andrew Critch, 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.
Alexei Andreev
Fixed, thanks.
Eric Bruylant
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.
Alexei Andreev
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.
Eric Bruylant
True, there may be odd exceptions. And yep, fixed :)
Eric Rogstad
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.
Eric Rogstad
What do you mean by this -- could you say more about how it's different from the previous reason?
Joe Zeng
In the body: you as a personal pronoun, y/n?
Eric Bruylant
Yes in guides and explanations, I think yes universally but pinging slack for opinions.
Alexei Andreev
Yes.