diff --git a/docs/5.0/docs.md b/docs/5.0/docs.md new file mode 100644 index 00000000000..ded69832608 --- /dev/null +++ b/docs/5.0/docs.md @@ -0,0 +1,80 @@ +# Quickstart + +Documentation is hard. Without structure over time it turns into a random collection of articles. + +## Getting Started + +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. + +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. + +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." + +!!! note + "Getting started" is a better term than "Quickstart". + Google "Getting started with React" vs "React quickstart" + and compare the search results. + +## 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 + +Integration guides explain how to set up Teleport with other tools, +for example "Access Workflows with Slack". + +### Best Practices + +Best practices guides are about best deployment and usage practices. +They sometimes take the form of patterns and anti-patterns. + +### Troubleshooting + +Troubleshooting guides list common failures and how to diagnose them, +they explain logs, remedies and tips and tricks. + +## Architecture + +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. + +### Networking + +Readers are interested to learn about ports, components and protocols used. + +### Security + +This section lists security protocols and primitives. +Secops look for an attack vector tree diagram. + +### Deployment + +Deployment diagram should explain components and how they interact with databases +and each other. + +## Reference manuals + +Reference manuals provide an exhaustive list of configuration options +and API methods. + +A good reference manual is search friendly and lists all content on the same page. + + +## Next Steps + +* Read more about [content best practices](./docs/best-practices.md). diff --git a/docs/5.0/docs/best-practices.md b/docs/5.0/docs/best-practices.md new file mode 100644 index 00000000000..b009a82813e --- /dev/null +++ b/docs/5.0/docs/best-practices.md @@ -0,0 +1,67 @@ +# Docs Best Practices + +## Content + +**Keep it simple** + +Read the book [On Writing Well](https://www.amazon.com/Writing-Well-Classic-Guide-Nonfiction/dp/0060891548). + +**Write for the target audience** + +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. + +**Keep guides self-contained** + +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: + +```bash +{% raw %}{{\!CHANGELOG.md\!}}{% endraw %} +``` + +## Diagrams + +Use [Teleport's lucidchart library](https://app.lucidchart.com/lucidchart/dfcf1f4a-5cf0-4758-8ebb-f6ea86900aba/edit) +to create diagrams with a consistent design language. + +## Videos + +Mac users should use Quicktime's `Cmd-Shift-5` to record a small part of the screen: + +![quicktime](../img/docs/quicktime.webp) + +**Convert Mov to MP4 and WebM** + +Quicktime outputs large `.mov` files. Use `ffmpeg` to convert them into `mp4` and `webm` +web-friendly formats: + +```bash +# create MP4 +ffmpeg -i input.mov -b:v 0 -crf 25 output.mp4 +# create WebM +ffmpeg -i input.mov -c vp9 -b:v 0 -crf 41 output.webm +``` + +**Embed videos** + +```html + +``` + +To test videos locally, add them to the `img/video` folder of the docs. +For production, upload to the website and refer from there: + +```html + +``` diff --git a/docs/5.0/img/docs/quicktime.webp b/docs/5.0/img/docs/quicktime.webp new file mode 100644 index 00000000000..edd09bc1ac8 Binary files /dev/null and b/docs/5.0/img/docs/quicktime.webp differ