This document should be used as a guideline when writing documentation and blog posts on tinacms.org
Brand
Capitalization: Tina, TinaCMS
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.
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 should stand out consistently from their surrounding text; avoid applying additional formatting. Links appearing within emphasized text may be formattedappropriately.
Link text should flow naturally in prose and relate semantically to the link target. Basically, just don't use "click here".