Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 Style Guide Content Update – Removing Links to Tina.org #2178

Merged
merged 3 commits into from
Sep 17, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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/)"*
Loading