Style guidelines

Hav­ing con­sis­tency across pages im­proves user ex­pe­rience and makes Ar­bital pages feel more pol­ished. This page lists guidelines to fol­low when writ­ing a page’s ti­tle, click­bait, sum­mary, and body text.

If there are any stylis­tic con­sid­er­a­tions you’d like clar­ified, com­ment here.

For style guidelines that ap­ply speci­fi­cally to the math do­main, see math style guidelines.

Global

Yes: US spel­ling and ter­minol­ogy noteOne day we’ll have lo­cal­iza­tion..

Title

Yes: “First let­ter is cap­i­tal”
Yes: “Is it okay for the ti­tle to be a ques­tion?”
Yes: “Short and sweet”
No: “Cap­i­tal­ize Every Word”
No: “**Mark­down**”
No: “Pe­riod at the end.”
No: “This is a long ti­tle that’s ba­si­cally a com­plete sen­tence of its own” (Use click­bait for that)

  • Ex­cep­tions: ask­ing a ques­tion or eval­u­at­ing a propo­si­tion

Clickbait

Yes: “First let­ter is cap­i­tal.”
Yes: “Pique user’s in­ter­est in the topic.”
Yes: “Most click­baits are just one sen­tence tel­ling user what they might find out if they read the page.”
Yes: “Can a click­bait ask the reader a lead­ing ques­tion?”
Yes: “Pe­riod or other punc­tu­a­tion at the end.”
Yes: Omit­ting click­bait if the ti­tle is de­scrip­tive enough.
No: “Cap­i­tal­ize Every Word”
No: “**Mark­down**”

Alias

  • Yes: “low­er­case­with­un­der­scores”

  • Yes: “us­ingful­l­words”

  • Yes: “be­speci­fic­style_guide” (as op­posed to “spe­cific”)

  • No: “abrv” (ab­bre­vi­a­tions)

  • No: “MUAs” (made up acronyms)

  • No: “ali­asthatis­cle­ar­ly­way­toolong­to­beuse­fu­lor_mem­o­rable”

  • If the alias has al­ter­nate mean­ings, e.g. “el­e­ment”, ap­pend the rele­vant do­main’s name, e.g. “el­e­ment­math­e­mat­ics” (or, for ar­bital do­main pages, prepend e.g. “ar­bitalstyle_guideline”).

  • Pre­fer sin­gle (“pen­guin”) to plu­ral ver­sion (“pen­guins”), if pos­si­ble.

Text body

Summary

Yes: Put it at the top of the page
Yes: Not hav­ing a sum­mary if the first para­graph is already a good sum­mary. Yes: “Para­graph long ex­pla­na­tion sum­ma­riz­ing the con­tents of the page…”
Yes: “Us­ing Mark­down as nor­mal.”
Yes: “If the page has a vote, de­scribe ex­actly what the vote is about.”

Body

Yes: Con­ver­sa­tional, fun tone.
Yes: We as a per­sonal pro­noun.
Yes: Ex­plain­ing things in what­ever way works best.
No: I as a per­sonal pro­noun.

Length

Most Ar­bital pages are be­tween one to five screens long. They are usu­ally much shorter than Wikipe­dia pages. It’s prob­a­bly best to break very long pages into a few shorter pages, es­pe­cially if they need to be used as req­ui­sites.

Yes: Us­ing a link when a con­cept is in­tro­duced or men­tioned within a sec­tion.
Yes: Us­ing a red link when you want to in­di­cate that there should be a page for that con­cept (with or with­out a ti­tle, i.e. dis­play text vs dis­play text).
Yes: Link glos­sary pages for over­loaded words.
No: “Us­ing the link in very close prox­im­ity to the link.”
No: Spec­i­fy­ing the ti­tle of the page ex­actly: Style guidelines, in­stead just do Style guidelines

Headers

Yes: Cap­i­tal­ize first let­ter and no pe­riod at the end
No: Header for the open­ing sec­tion
No: “Pe­riod or other punc­tu­a­tion at the end.”

Children:

Parents:

  • Contributing to Arbital

    Want to help Ar­bital be­come awe­some?

    • Arbital

      Ar­bital is the place for crowd­sourced, in­tu­itive math ex­pla­na­tions.