Docs: Redesign the UX for discovering references and architectural information

[ptgott]

Applies To

Planning the exact guides to change is part of the scope of the project. We will need to make a plan first.

Details

As with other docs sites, Teleport's docs organize pages according to a fourfold taxonomy: getting started guides, how-to guides, references, and conceptual/architecture guides. The information architecture of the Teleport docs site is not consistent in how we organize references and architecture guides.

Current approaches

We have three different approaches to organizing references and architectural docs:

• Docs-scoped with dedicated sections: There are dedicated docs sections for architecture guides (/docs/architecture/ and references (/docs/reference/). These sections are scoped across all of Teleport, with individual guides related to specific topics/themes.
• Feature-specific subsections: We organized the Login Rules docs into a subsection of "Access Controls", including a reference, how-to guide, and conceptual introduction. These are specific to Login Rules.
• Section-wide reference/architecture guide: A few of our top-level docs sections have an architecture guide or reference guide, e.g., the Database Access section. These are scoped to an entire product area rather than a specific feature.

Problems

Adoption

Some users would rather have a combination of detailed architectural guides and references than follow how-to guides. These users are experienced engineers and can figure out the necessary commands to run or configuration options to provide as long as they understand how a system works (with architectural guides) and how to interact with it (references).

It might be the engineer's full-time job for several days or weeks to set up Teleport, giving them time to read architectural guides and references in order to become an expert at Teleport.

We should ensure that engineers who prefer to use references/architecture guides can learn everything they need to about Teleport. Every feature needs to have adequate coverage in a reference guide and architecture guide.

Scaling the documentation

As we develop new Teleport features, we need a consistent approach to organizing the documentation for these features so:

• docs authors (who are often/usually engineers) can minimize the time they spend writing new docs
• in general, there's a clear place to put new information

Possible solution

• Spell out an explicit approach in the docs style guide: There are reasons to prefer each of the three approaches we use above, but we should be consistent and explicit about which approach we choose. Ideally, we should only choose a single approach.
• Consider automatically discovering features that aren't covered in architecture and reference guides. We could do this by:
  • Including feature- and guide-type-related keys in the Markdown frontmatter of each docs page, e.g., type: architecture or type:reference, plus feature:login-rules or feature:device-trust. We could then use a script to check whether each feature corresponds to an architecture guide, reference, and how-to guide. This will only work if we scope reference and architecture pages to a single feature.
  • We could also check to see if any keys inside yaml code snippets or flags within code snippets within how-to guides are missing in references/architecture guides.

Related Issues