Skip to content

Commit

Permalink
📝 Style Guide Content Update – Removing Links to Tina.org (#2178)
Browse files Browse the repository at this point in the history
* TinaCMS content update

* TinaCMS content update

---------

Co-authored-by: tina-cloud-app[bot] <58178390+tina-cloud-app[bot]@users.noreply.github.com>
Co-authored-by: Isaac Lombard [SSW] <152236421+isaaclombardssw@users.noreply.github.com>
  • Loading branch information
tina-cloud-app[bot] and isaaclombardssw committed Sep 17, 2024
1 parent 724b70b commit b87ff19
Showing 1 changed file with 34 additions and 31 deletions.
65 changes: 34 additions & 31 deletions content/docs/contributing/style-guide.mdx
Original file line number Diff line number Diff line change
@@ -1,50 +1,53 @@
---
title: Style Guide
id: /docs/contributing/style-guide
title: Style Guide
last_edited: '2024-09-11T05:35:54.162Z'
next: ''
previous: ''
---

This document should be used as a guideline when writing documentation and blog posts on [tinacms.org](http://tinacms.org)
This document should be used as a guideline when writing documentation and blog posts on [tinacms.io](http://tinacms.io)

## 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**."_
* 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](http://hemingwayapp.com/) can help identify overly complicated prose.
* 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](http://hemingwayapp.com/) 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](https://github.com/tinacms/tinacms.org/blob/master/README.md#copy-able-code-block) 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.
* 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](https://github.com/tinacms/tinacms.org/blob/master/README.md#copy-able-code-block) 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](https://title.sh/) for help.
* 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](https://title.sh/) for help.

### Links

- Avoid using `code tags` in [links](https://tinacms.org).
- [Links](https://tinacms.org) should stand out _consistently_ from their surrounding text; avoid applying additional formatting. _[Links](https://tinacms.org) appearing within emphasized text_ may be [**formatted**](https://tinacms.org) **appropriately**.
- Link text should flow naturally in prose and relate semantically to the link target. Basically, just don't use "[click here](https://tinacms.org)".
- _Example: "swing by [our community forum](https://community.tinacms.org/)"_
* Avoid using `code tags` in [links](https://tinacms.io).
* [Links](https://tinacms.io) should stand out *consistently* from their surrounding text; avoid applying additional formatting. *[Links](https://tinacms.io) appearing within emphasized text* may be **[formatted](https://tinacms.io)** **appropriately**.
* Link text should flow naturally in prose and relate semantically to the link target. Basically, just don't use "[click here](https://tinacms.io)".
* *Example: "swing by [our community forum](https://tina.io/community/)"*

0 comments on commit b87ff19

Please sign in to comment.