Skip to content

Further clarify documentation that is template-only vs documentation that should be included in a repo that uses this template #581

@rocketnova

Description

@rocketnova

In places, it is unclear when reading the documentation in this repo whether the documentation is for:

  1. The template. We want documentation that explains how to use the template and how it works with other templates. The audience for this documentation are the engineer(s) that initially set up the repo, as well as any engineers that might want to pull in changes in the future.
  2. The child repo. We want documentation that a child repo can inherit that explains what it inherited and how to use it (e.g. a system architecture diagram, instructions for how to run make commands). The child repo should modify that documentation and make it specific to its project context. The audience for this documentation are the project engineers that onboard to a project after it has been setup.

The confusion between which audience a piece of documentation is for has become increasingly clear while working with users that are brand new to our template ecosystem. We should do another pass at trying to clarify this so that the templates are more approachable for new users.

Metadata

Metadata

Assignees

No one assigned

    Labels

    cloud: awsApplies to AWS templatecloud: azureApplies to Azure templatescope: documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions