ptgott
commented
1 year ago Going to close this, since we aren't requiring that each docs guide set up a full Teleport installation any more (https://github.com/gravitational/teleport/pull/20024). As a result, it's inevitable that a Prerequisites section will contain links to other guides.
Details
In this review of the PR that added the Machine ID Ansible guide, which was submitted after the guide was merged, klizhentas pointed out that in how-to guides, we should avoid breaking the reader's focus by requiring them to complete another guide first (see the documentation style guide).
In the Prerequisites section of this guide, along with other guides in our docs, there are links to other pages on our docs site that could break a reader's focus. Let's find a way to use partials and the
(! !)syntax to avoid directing a reader away from our how-to guides.I used the following script, based on another script I used for a similar purpose, to find docs pages with links to other docs pages in the Prerequisites section. We can also look into removing docs links from other sections, though these would be harder to spot automatically. The Prerequisites section is the only one that is unique to how-to guides, and it was straightforward to identify links in this section with a script. (Maybe we could use frontmatter to identify guides by type, e.g.,
how-to,getting-started,reference, etc.?)Here are the results:
Category