mirror of https://github.com/cncf/techdocs.git
50 lines
1.7 KiB
Markdown
50 lines
1.7 KiB
Markdown
---
|
|
title: Implementing _PROJECT_ Doc Improvements
|
|
tags: [_PROJECT_]
|
|
---
|
|
|
|
<!-- markdownlint-disable no-duplicate-heading -->
|
|
|
|
## Introduction
|
|
|
|
This document provides actionable suggestions for improving the _PROJECT_
|
|
technical documentation.
|
|
|
|
For an analysis and general discussion of recommendations on _PROJECT_ technical
|
|
documentation, see [analysis.md](analysis.md).
|
|
|
|
### Recommendations, requirements, and best practices
|
|
|
|
This analysis measures documentation against CNCF project maturity standards and
|
|
suggests possible improvements. In most cases there is more than one way to do
|
|
things. Few recommendations here are meant to be prescriptive. Rather,
|
|
recommendations are based on documentation best practices as understood by the
|
|
reviewers. The recommended implementations represent the reviewers' experience
|
|
with how to apply those best practices. In other words, borrowing terminology
|
|
from the lexicon of [RFCs][rfc-keywords], the changes described here should be
|
|
understood as "recommended" or "should" at the strongest, and "optional" or
|
|
"may" in many cases. Any "must" or "required" actions are clearly denoted as
|
|
such, and pertain to legal requirements such as copyright and licensing issues.
|
|
|
|
The top-level documentation recommendations for this project are:
|
|
|
|
> AUTHOR NOTE: Provide a summary or outline of the recommendations. Depending on
|
|
> the analysis findings, recommended actions might be organized into two or
|
|
> three high-level items that contain multiple actions, or might just be a list
|
|
> of independent changes. For examples, see a completed implementation plan such
|
|
> as 0008-Backstage or 0010-etcd.
|
|
|
|
## High-level action 1
|
|
|
|
### Issue 1
|
|
|
|
### Issue 2
|
|
|
|
## High-level action 2
|
|
|
|
### Issue 1
|
|
|
|
### Issue 2
|
|
|
|
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119
|