Skip to content

Commit

Permalink
[v6.1] Merge style guide into docs (#6571)
Browse files Browse the repository at this point in the history 
* docs: best practices

* docs: requested changes

* docs: slight rewording

* docs: make changes
  • Loading branch information
@inertial-frame
inertial-frame authored Apr 26, 2021
1 parent f0d3067 commit a39bfef
Show file tree
Hide file tree
Showing 2 changed files with 162 additions and 95 deletions.
110 changes: 63 additions & 47 deletions docs/pages/docs.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,80 +2,96 @@
title: Quickstart
---

Documentation is hard. Without structure over time it turns into a random collection of articles.
This article serves as the primary entry-point all things documentation-related.

## Getting Started
- If you have an idea to improve the docs tooling, submit a ticket over in the [Next](https://github.com/gravitational/next) repo.
- If you have an idea to improve the docs (an article, post, example, etc.), submit a ticket over in the [Teleport](https://github.com/gravitational/teleport) repo.

Getting started guides are self contained articles and should get a user going
following the shortest path.
They are for beginners, people who may have never heard about Teleport before.
A good quickstart takes 5-10 minutes, starts with benefits and a demo video.
## Our documentation philosophy

For example, an article can start with "SSO and Audit for Kubernetes in 3 steps".
Then it follows with a demo video. Prerequisites and tools used should
go next. Two-three sub-sections with the setup. Wrap up with "Next steps" section.
Documentation is:

Getting started guides should try hard to keep a busy user engaged. It calls out each step and where the user
is in the sequence, for example "Step 1 out of 3. Adding a local user."
- Often thankless. Often neglected, it can make or break teams when they encounter a stumbling block.
- Hard. Without structure, over time, it turns into a random collection of articles.
- Essential when learning - whether one's a new or a seasoned engineer.
- Often the final arbiter of disputes and disagreements. Reference documentation is often the ultimate source of truth about a product, service, or tool.
- **At best:** an arm of Engineering, an advocate for developers, enpowerment for learning, and definitive resolution for customers.
- **At worst:** a disorganized morass of inaccurate and unhelpful jargon.
- Supplements other support mediums like Stack Overflow, support forums, GitHub issues, Slack, and so on. There are many customer voices and we want to hear them all. As such, we provide several avenues for expression, questions, and feedback.
- Not marketing although it plays a role in onboarding customers. Page views matter, but accuracy and customer satisfaction matter most.
- Often essential to leadership when they're evaluating a product. Doubly so when potential customers are in high-regulation spaces like finance or government. Many teams neglect their documentation only to fail to secure (or have delayed) the lucrative contracts that such potential customers can bring.

## Kinds of documents

This section ennumerates the most-common kinds of documents we write at Teleport and include within our document set.

### Getting started articles

*Getting started guides* are self-contained, *quickstart*, articles and should aim to get a user up and running in the shortest way.

These are designed for beginners, often people who may not have heard about Teleport before.

A good *quickstart* takes 5-10 minutes, states the utility of completing the article at the beginning, and a demo video.

Example:

1. Getting started title: `"SSO and Audit for Kubernetes in 3 steps"`
2. Followed by a demo video.
3. Prerequisites and tools used should go next.
4. Two-three sub-sections with the setup.
5. Wrap up with "Next steps" section.

Getting started guides should be written with the goal to keep a busy user engaged.

Each step is clearly stated so users can easily follow the sequence: "Step 1 out of 3. Adding a local user."

<Admonition type="note">
"Getting started" is a better term than "Quickstart".
Google "Getting started with React" vs "React quickstart"
and compare the search results.
</Admonition>

## Guides

Guides are self-contained articles for intermediate-level readers setting up Teleport
for a specific scenario.
For example, "Kubernetes Access on GKE" features high availability setup,
using Firebase and GCS backend.

It's OK to have duplicate content between different guides. Readers should be able to
scroll down a single guide and get to a result without leaving the page.
Guides start with a purpose, followed by prerequisites, setup steps and next steps.

### Integrations
### Guides

Integration guides explain how to set up Teleport with other tools,
for example "Access Workflows with Slack".
*Guides* are self-contained articles for intermediate readers (readers with some familiarity working with Teleport already) setting up Teleport for a specific scenario.

### Best Practices
Example:

Best practices guides are about best deployment and usage practices.
They sometimes take the form of patterns and anti-patterns.
1. Guide title: "Kubernetes Access on GKE" which features a high availability setup using Firebase and GCS backend.
2. Followed by the guide purpose.
3. Followed by prerequisites.
4. Next, the setup steps.
5. Wrap up with "Next steps" section.

### Troubleshooting
It's OK to have duplicate content between different guides. In many cases this is encouraged for ease and familiarity.

Troubleshooting guides list common failures and how to diagnose them,
they explain logs, remedies and tips and tricks.
Readers should be able to scroll down the guide and get to the end without leaving the page. Do not use an anchor or HTML link to describe some step - concisely, include the steps within the guide.

## Architecture
Specific kinds of *guides* include:

Architecture explains how Teleport works to advanced readers.
It is often an architect, devsecops or other professional reading these guides
to make a decision on whether and how to use Teleport.
1. **Integration** - *integration guides* explain how to set up Teleport with other tools. E.g. - "Access Workflows with Slack".
2. **Best Practices** - *best practices guides* are about best deployment and usage practices. They sometimes describe common patterns and anti-patterns.
3. **Troubleshooting** - *troubleshooting guides* list common failures and how to diagnose them, they explain logs, remedies and tips and tricks.

### Networking
### Architecture

Readers are interested to learn about ports, components and protocols used.
*Architecture* articles explain how Teleport works to advanced readers. Architects, devsecops, or similar professional constitute the most-common audience.

### Security
These articles are used to make a decision about whether and how to use Teleport.

This section lists security protocols and primitives.
Secops look for an attack vector tree diagram.
Specific kinds of *architecture* articles include:

### Deployment
1. **Networking** - readers are interested in learning about specific ports, components, and protocols that are or can be used.
2. **Security** - lists security protocols and primitives. Secops will look for an attack vector tree diagram. Make sure to include these sections when appropriate!
3. **Deployment** - should include a deployment diagram which in turn explains components and how they interact with databases and each other.

Deployment diagram should explain components and how they interact with databases
and each other.
### Reference manuals

## Reference manuals
*Reference manuals* provide an exhaustive list of configuration options and API methods (*reference documentation*).

Reference manuals provide an exhaustive list of configuration options
and API methods.
HTML or Markdown tables are often the best formats for this kind of article (or sections within them).

A good reference manual is search friendly and lists all content on the same page.
A good *reference manual* is search friendly and lists all content on the same page.

## Next Steps

Expand Down
147 changes: 99 additions & 48 deletions docs/pages/docs/best-practices.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,44 @@
---
title: Docs Best Practices
description: Best practices for documentation
---

## Content
# Documentation Best Practices

**Keep it simple**
This article serves to define [documentation](../docs) best practices.

Read the book [On Writing Well](https://www.amazon.com/Writing-Well-Classic-Guide-Nonfiction/dp/0060891548).
## Work Flow

**Write for the target audience**
This section describes the general workflow for writing documentation:

Do not overload getting started guides with content and complex terminology, focus
on benefits to the user. Do not add architecture diagrams in getting started guides.
Likewise, do not do demos in architecture articles.
1. Select a branch from [github.com/gravitational/teleport](https://github.com/gravitational/teleport/) corresponding to the version of the documentation/product you'd like to work on.
2. Use `$ git submodule update --init --recursive` when you `git switch` to or `git checkout` a new branch.
3. Make changes locally using [Next](https://github.com/gravitational/next), our primary documentation tool.
4. Validate your changes locally using the provided [linters](https://github.com/gravitational/next#development-related-commands).
5. Commit your changes and create a PR.
6. Get approved and merge your changes in.

**Keep guides self-contained**
Typically if you make changes to some version `6.1`, you'll also want to port those changes to `master/main`, and any version following `6.1`.

All guides should have everything that is needed for a reader
to accomplish their goal. This sometimes leads to duplication.
Use include directives for repeated content. Remove backslash before the exclamation marks for it to work:
In other words, making changes to `6.1` usually entails making changes to `6.2` and `7.0 (master/main)`. This isn't universally the case (if some document or change is specific to a single version) but generally applies. Eventually most of this will be automated since it can be a bit cumbersome.

```bash
(\!CHANGELOG.md\!)
```
To see the current submodule and version mappings review [the mappings](https://github.com/gravitational/next/blob/main/.gitmodules).

## Tooling

Filepath should be relative to the repository root folder.
Our documentation is primarily built with [Next](https://github.com/gravitational/next) which has the following features:

## Diagrams
1. It compiles React and specifically, React within Markdown. This gives us the ability to create uniform UI/UX markers (the resuable UI/UX components React is known for) that engage and help the reader.
2. Lints and checks both React and native language *within* Markdown as part of the CI/CD and PR process.
3. Several pre-compilation plugins, processors, and hooks that we can extend as needed. This gives us a lot of power and flexibility to automate some of the more tedious tasks.

Use [Teleport's lucidchart library](https://app.lucidchart.com/lucidchart/dfcf1f4a-5cf0-4758-8ebb-f6ea86900aba/edit)
to create diagrams with a consistent design language.
**Diagrams:**

## Videos
- Use [Teleport's lucidchart library](https://app.lucidchart.com/lucidchart/dfcf1f4a-5cf0-4758-8ebb-f6ea86900aba/edit) to create diagrams with a consistent design language.

Mac users should use Quicktime's `Cmd-Shift-5` to record a small part of the screen:
**Videos:**

- Mac users should use Quicktime's `Cmd-Shift-5` to record a small part of the screen:

![quicktime](../../img/docs/quicktime.webp)

Expand Down Expand Up @@ -70,26 +75,69 @@ Your browser does not support the video tag.
</video>
```

## Custom syntax used in the docs
## Style guide

Some standards are presently codified in the [Next](https://github.com/gravitational/next) repository by way of MDX linters. Make sure to use these.

The following standards are already in use. Please follow them (although these are non-blocking, do read the comments below):

1. `tsh`, `tctl`, and other core commands should be placed in tic marks.
2. All ports or values should be enclosed in tic marks `443`.
3. Footnotes should be ordered by appearance (chronological precedence). `2` should not come before `1`.
4. Tend to write sparser one to two-sentence groupings rather than lengthier text block paragraphs.
5. Use periods at the end of a line even in a list.
6. Use lists aggressively.

The rest are subject to final approval by the developer relations team. In general, it's still a good idea to adopt some of these when writing your next article:

1. Consistent header casing (`I am an example header`, `I Am another Example header`, `I am a Third header`).
2. Consistent acronyms and concept keyword use (`2-factor`, `two-factor`, `2fa`, `tfa`).
3. We should avoid using scare-quotes `""` to refer to a sub-service/proper noun - these often have negative connotations associated with them. E.g. - "Trusted Cluster" vs *Trusted Cluster*. Use italics for concept keywords and tic marks for values. (Clarification: it's harmless to use quotes to approximate or indicate something but not to name or refer to a proper noun. It can be quite conversational and friendly in those other contexts.)
4. Consistent use of contractions - many teams tend to favor an all or nothing approach here. Contractions keep the language sparse, concise, and conversational. For more formal language, we'd probably want to avoid them.
5. Use numbered lists for any sequence of steps.
6. Product proper nouns should be capitalized. `trusted cluster` -> `Trusted Cluster`
7. Product proper nouns should be bolded. `Trusted Cluster` -> **Trusted Cluster**
8. Acronyms should always be introduced following a concept keyword and then consistently used thereafter (no concept keyword used) in an article (saves space, typing, and reading - gaurantees the shorthanded term is available).

**Pros:**

- These are relatively minor improvements overall but help to set more uniform documentation standards.
- Stylistically, this helps to ensure more more professional, neat, and tidy docs.
- Helps set clear, baseline, guidelines we can expand as documentation needs expand. We can apply these uniformly for blogs, docs, etc.
- May assist with any future localization efforts since setting a config file for a language is easier when words are one-to-one.
- Assists with improving searches by content or keyword.
- Acronyms are occasionally (but only very rarely) associated with multiple concepts. This reduces some potential ambiguities. (Especially for concepts that exist in a complex and particularly acronym-prone space.)
- These are often helpful for new hires since they can simultaneously be reading and learning the material while performing basic editing.
- Consistent and helpful styling has an impact on customer satisfaction. Small stylistic changes can improve the efficacy of docs. It's a lot easier to find that *one, crucial, config value* if it's bolded or highlighted.

### Varibles
## Testing

To prevent updating links and code examples after each release, we can replace them with
variables. This way, it will be enough to update them in one place.
1. Make sure to manually test commands and steps.
2. Make sure to run linting on your docs.

Variables are stored in the `docs/config.json` file under the key `variables`.
Variables can be nested inside the config.
## MDX and UI/UX components

To insert variabe to the page use `(\= path.to.variable \=)` syntax
(remove backslashes in actual code).
Next uses Markdown with React (hence, the `.mdx` filename suffix).

Variables will be linted on CI. If the variable didn't exist in the config, it would cause an error.
- MDX supports powerful templating features like variable interpolation.
- This section briefly describes some of the features that're most relevant when writing documentation.

### Variables, templating, and interpolation

Many documentation teams struggle with maintaining the vast number of articles and resources that are eventually created and consumed. Links and images have to be rechecked for accuracy/relevance.

To ease this burden, we can replace links and code examples with *variables* so we don't have to constantly update everything after each release.

- Variables are stored in the `docs/config.json` file under the key `variables`.
- Variables can be nested inside the config.
- To insert variabe to the page use `(\= path.to.variable \=)` syntax (remove backslashes in actual code).
- Variables will be linted when a PR is created as part of our CI/CD process. If the variable didn't exist in the config, it would throw an error which you must remedy in order to merge.

### Includes

To prevent content duplication, it may be useful to include code examples or other
MDX files inside the current page. To do it use `(\! path-to-file.mdx \!)` syntax (remove
backslashes in actual code).
To prevent content duplication, it's very useful to include code examples or other MDX files inside the current page (akin to API or code-reuse). This allows documentation to reduce maintenance overhead and focus on writing new articles.

Use `(\! path-to-file.mdx \!)` syntax (remove backslashes in actual code).

Paths are resolved from the root of the repository.

Expand All @@ -105,7 +153,7 @@ Includes will only work in these two cases:
Some other text.
```

If the include is an `mdx` file, it will be parsed and rendered as a markdown. In other cases
If the include is an `mdx` file, it will be parsed and rendered as a markdown. In other cases
it will be included as-is.

2. Include inside the code blocks. E. g.:
Expand All @@ -121,26 +169,28 @@ Includes will only work in these two cases:

These will be inserted as-is, even in the case of the `mdx` files.

Includes in any other places will not be resolved and will be left as is.

Includes will be linted on CI. If the file didn't exist in the repository,
it would cause an error. Wrong placement of includes will also cause errors.
- Includes in any other places will not be resolved and will be left as is.
- Includes will be linted when a PR is created as part of our CI/CD process.
- If the file didn't exist in the repository, it will throw an error. Wrong placement of includes will also throw errors.

### Image pixel density marker

The browser can't distinguish between retina-ready and not retina-ready images.
Because of this, screenshots made on the retina screens may look large on the page.

To hint to the browser that the images are meant for retina display, we can add
the suffix `@Nx` to the image's file name. For example, screenshots made on macOS
should have the suffix `[email protected]`. It will tell the browser to scale images
down twice to show them in their actual size. Different OSes may require different
suffixes based on which logical and physical resolutions their screens have.
- The browser can't distinguish between retina-ready and not retina-ready images.
- Because of this, screenshots made on the retina screens may look large on the page.
- To hint to the browser that the images are meant for retina display, we can add
the suffix `@Nx` to the image's file name. For example, screenshots made on macOS
should have the suffix `[email protected]`.
- It will tell the browser to scale images
down twice to show them in their actual size.
- Different Operating Systems may require different suffixes based on which logical and physical resolutions their screens have.

### Admonitons

<Admonition title="Admontion title" type="tip">
Admontion content.
<Admonition
title="Admontion title"
type="tip"
>
Admontion content.
</Admonition>

If you want to add admonition like the one above to the page use this syntax:
Expand All @@ -151,7 +201,7 @@ If you want to add admonition like the one above to the page use this syntax:
</Admonition>
```

`type` can be one of the following values: `warning`, `tip`, `note`, `danger`.
`type` can be one of the following values: `warning`, `tip`, `note`, `danger`.
Different types will result in different colors for the header. Omitting the type
or using some other value will result in resetting it to the `tip`.

Expand All @@ -163,6 +213,7 @@ If `title` is omitted, `type` will be used instead as the title value.
<TabItem label="First label">
First tab.
</TabItem>

<TabItem label="Second label">
Second tab.
</TabItem>
Expand Down

0 comments on commit a39bfef

Please sign in to comment.