To contribute new documentation, follow these steps:
- Identify the audience and intended use for the information.
- Choose the type of content you wish to contribute.
- Use one of the new content templates:
- Concept -- Conceptual topics explain how things work or what things mean. They provide helpful context to readers. They do not include procedures.
- Procedure -- Procedural (how-to) topics include detailed steps to perform a task as well as some context about the task.
- Troubleshooting -- Troubleshooting topics list common errors and solutions.
- Blog -- Instructions and a template that you can use to help you post to the Knative blog.
- Choose appropriate titles and filenames.
- Write your new content. See the style guide to help you with this process. Feel free to reach out to the DUX working group with any questions.
- Open a PR in the knative/docs GitHub repository to kick off the review process. For details, see our Using GitHub help.
The best documentation starts by knowing the intended readers, their knowledge, and what you expect them to do with the information. Otherwise, you cannot determine the appropriate scope and depth of information to provide, its ideal structure, or the necessary supporting information. The following examples show this principle in action:
-
The reader needs to perform a specific task. Tell them how to recognize when the task is necessary, and provide the task itself as a list of numbered steps. Don’t simply describe the task in general terms.
-
The reader must understand a concept before they can perform a task: Before the task, tell them about the prerequisite information and provide a link to it.
-
The reader needs to make a decision: Provide the conceptual information necessary to know when to make the decision, the available options, and when to choose one option instead of the other.
-
The reader is an administrator but not a SWE: Provide a script, not a link to a code sample in a developer’s guide.
-
The reader needs to extend the features of the product: Provide an example of how to extend the feature, using a simplified scenario for illustration purposes.
-
The reader needs to understand complex feature relationships: Provide a diagram showing the relationships, rather than writing multiple pages of content that is tedious to read and understand.
The most important thing to avoid is the common mistake of simply giving readers all the information you have, because you are unsure about what information they need.
If you need help identifying the audience for you content, we are happy to help and answer all your questions during the DUX working group weekly meetings.
When you understand the audience and the intended use for the information you provide, you can choose content type that best addresses their needs. To make it easy for you to choose, the following table shows the supported content types, their intended audiences, and the goals each type strives to achieve:
| Content type | Goals | Audiences |
|---|---|---|
| Concept | Explain some significant aspect of Knative. For example, a concept page describes the configuration model of a feature and explains its functionality. Concept pages don't include sequences of steps. Instead, provide links to corresponding tasks. | Readers that want to understand how features work with only basic knowledge of the project. |
| Reference | Provide exhaustive and detailed technical information. Common examples include API parameters, command-line options, configuration settings, and advanced procedures. Reference content is generated from the Knative code base and tested for accuracy. | Readers with advanced and deep technical knowledge of the project that needs specific bits of information to complete advanced tasks. |
| Example | Describe a working and stand-alone example that highlights a set of features, an integration of Knative with other projects, or an end-to-end solution for a use case. Examples must use an existing Knative setup as a starting point. Examples must include an automated test since they are maintained for technical accuracy. | Readers that want to quickly run the example themselves and experiment. Ideally, readers should be able to easily change the example to produce their own solutions. |
| Procedure | Shows how to achieve a single goal using Knative features. Procedures are written as a sequence of steps. Procedures provide minimal explanation of the features, but include links to the concepts that provide the related background and knowledge. Procedures must include automated tests since they are tested and maintained for technical accuracy. | Readers that want to use Knative features. |
| Setup | Focus on the installation steps needed to complete an Knative deployment. Setup pages must include automated tests since they are tested and maintained for technical accuracy. | New and existing Knative users that want to complete a deployment. |
| Blog |
Focus on Knative or products and technologies related to it. Blog posts fall in one of the following three categories:
|
Readers with a basic understanding of the project who want to learn about it in an anecdotal, experiential, and more informal way. |
| News | Focus on timely information about Knative and related events. News entries typically announce new releases or upcoming events. | Readers that want to quickly learn what's new and what's happening in the Knative community. |
| FAQ | Provide quick answers to common questions. Answers don't introduce any concepts. Instead, they provide practical advice or insights. Answers must link to tasks, concepts, or examples in the documentation for readers to learn more. | Readers with specific questions who are looking for brief answers and resources to learn more. |
| Operation guide | Focus on practical solutions that address specific problems encountered while running Knative in a real-world setting. | Service mesh operators that want to fix problems or implement solutions for running Knative deployments. |
Choose a title for your new content, either a new page title or a title for a section that you want to add. Make sure it includes the keywords you want search engines to find and use sentence style capitalization.
The filename of your new content should reflect the title.
If the content that you add include a new folder, name that folder using the keywords that cover the scope of the content in the folder, separated by hyphens, all in lowercase. Keep folder names as short as possible to make cross-references easier to create and maintain. You should only need to create a new folder if you are adding multiple topics/files, or if you are grouping related content. The names for each file do not need to repeat the folder name since that context is already established.
TODO: link to intended documentation layout. A general warning about Conway's Law: documents will naturally tend to be distributed by team that produced them. Try to fight this, and organize documents based on where the reader will look for them. (i.e. all tutorials together, maybe with indications as to which components they use, rather than putting all serving tutorials in one place)
In some cases, the right place for a document may not be on the docs website — a blog post, documentation within a code repo, or a vendor site may be the right place. Be generous with offering to link to such locations; documents in the main documentation come with an ongoing cost of keeping up to date.
Learn about documenting code samples
Generally, the knative/docs repo contains Knative-specific user-facing content and blog content.
When you add a new document to the /docs directory, the navigation menu updates automatically.
For more information, see the
MkDocs documentation.
Contributor-focused content belongs in one of the other Knative code repositories
(knative/serving, knative/eventing, etc).
For information about which branch you should choose and how to cherrypick, see Branches and cherrypicking.
If you are not familiar with GitHub, see our working with GitHub guide to learn how to submit documentation changes.