Style Guide

This document should be used as a guideline when writing documentation and blog posts on tina.io

Brand

• Capitalization: Tina, TinaCMS, TinaCloud
• When discussing the project as a whole, Tina and TinaCMS can be used interchangeably.
• Prefer Tina over TinaCMS when discussing specific packages or components and their relation to the project.
  • Example: "The sidebar is the primary interface in Tina."

Tone

• Aim for a friendly, personal tone
• Documentation and tutorials should feel free to address the reader
  • Example: "If you want to see a glimpse of what you can do with a blocks-based content strategy, fork Tina Grande and give it a try."
• Tutorial steps should use an inclusive POV ("we" over "you")
  • Example:"Let’s say, instead of a single name, we’re storing a list of names like this:"
• While you don't need to follow it dogmatically, running your drafts through the Hemingway Editor can help identify overly complicated prose.

Formatting

• Inline and block code tags should be reserved exclusively for communicating code.
  • "Code" in this case can include source code, terminal commands, variable names, and package names.
  • The above is not meant to be an exhaustive list, but use your best judgement.
  • Avoid code tags when discussing interface elements (such as navigation menus and in-app actions). Opt for bold text instead.
  • Code blocks should be made copy-able unless they show more context then should be copied (i.e. diffs)
• Important concepts should be formatted in bold (strong emphasis).
• Other points of emphasis can be formatted in italics (normal emphasis), or bold (strong emphasis) as appropriate.
• When an emphasized phrase appears near a highlighted concept, opt for italics over bold for the former.
• Avoid emphasis fatigue! Too much emphasized text clustered together will lose its emphasis. Over-reliance on emphasis may indicate a lack of clarity in the writing.

Headings

• Each document should have a single top-level heading. On the tinacms.org website, this is handled by the title front matter field.
• Headings should follow strict hierarchy. Don't nest an h3 directly inside an h1 without an h2 in between.
• Don't nest headings more than three levels deep, inclusive of the top-level heading (h1 > h2 > h3). If you find the need to use a fourth-level heading, consider reorganizing the document or splitting it up.
• Headings can include italics, but avoid bold text or code tags.
  • Use italics formatting for code-like items when present in headings
• Make an effort to capitalize titles appropriately. Check out title.sh for help.

Links

• Avoid using code tags in links.
• Links should stand out consistently from their surrounding text; avoid applying additional formatting. Links appearing within emphasized text may be formatted appropriately.
• Link text should flow naturally in prose and relate semantically to the link target. Basically, just don't use "click here".
  • Example: "swing by our community forum"