Adds guidelines for writing docs

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).

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
+<video autoplay loop muted playsinline>
+  <source src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.mp4" type="video/mp4" />
+  <source src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.webm" type="video/webm" />
+Your browser does not support the video tag.
+</video>
+```
+
+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
+<video autoplay loop muted playsinline>
+  <source src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.mp4" type="video/mp4">
+  <source src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.webm" type="video/webm">
+Your browser does not support the video tag.
+</video>
+```