* Update the docs style guide
- Add the instruction not the recreate content where unnecessary to the
"How-to guides" section in addition to the "Getting started" section,
since this was intended to apply to both kinds of guides.
- Change the requirement to include a video with Getting Started guides
to a suggestion, matching our current practices.
- Add instructions to use technically precise language.
* Partially respond to PR feedback
* Respond to PR feedback
* Add instructions for backporting PRs
Our docs contribution guide already includes instructions for
backporting manually, but doesn't document the two automatic backport
method we support: backporting via GitHub labels and backporting via
`make`.
* Respond to PR feedback
* Respond to PR feedback
* Fix resource links
Fixes#12839
Some video links still refer to the outdated "/teleport/" path.
This change adds the videos these links refer to to the "img"
directory and updates the links.
Note that two of the three MDX files that are changed here do not
actually render the video. I've changed the links here anyway in
case someone uses these as a reference for the link format.
* Apply suggestions from code review
Co-authored-by: Ben Arent <ben@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
Co-authored-by: Ben Arent <ben@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
We recently gave "bash" code blocks the same functionality as
"code" blocks, and I wanted to document this. I realized that there
is no documentation for code snippets in the UI reference.
Since we can now adjust the visibility of Admonitions based on scope,
this change explains how the `scope` and `scopeOnly` attributes work
in the Admonition component within the docs UI reference.
Make our docs guidance discoverable
Currently, our guidance for making docs changes is
organized into a /docs/docs page that is only accessible if
you know the URL. This change ensures that people who have not
received an informal training on docs contributions can
contribute in a way that abides by our expectations for
consistency and effectiveness.
- Splits the docs/docs and docs/docs/best-practices pages into
a UI reference, getting started guide, and style guide. This
ensures that each kind of content we have in our contributing
guide (i.e., tutorial or reference) is accessible from the
main nav menu.
- Adds a "Contributing" tab to the navigation menu. There is
one subsection here related to documenation, and we can add
another subsection later with developer guides for editing
Teleport's code.
- Moves the "philosophy" section into the intro page of the
documentation contribution section menu.
- Makes various edits to the original docs guidance for clarity.
- Document our docs labels in a dedicated "creating an issue"
page
Fixes#9538
Paul Gottschling