Style guidelines

https://arbital.com/p/arbital_style_guide

by Alexei Andreev Nov 13 2015 updated Aug 6 2016

Various stylistic conventions people should follow on Arbital


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)

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

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.

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

Yes: Put it at the top of the page Yes: Not having a summary if the first paragraph works fine\. 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\."

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

Yes: Using a red link when you want to indicate that there should be a page for that concept\. Yes: Using a red link when you want to indicate that more could be explained about that concept\.

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.