creating-code-samples.md

Creating code samples

There are currently two general types of content that focus on code samples, either internal contributor content, or external-facing user content.

Contributor-focused content

• Documentation: Includes content that is component specific and relevant only to contributors of a given component. Contributor focused documentation is located in the corresponding docs folder of that component's repository. For example, if you contribute code to the Knative Serving component, you might need to add contributor focused information into the docs folder of the knative/serving repo.

• Code samples: Includes contributor related code or samples. Code or samples that are contributor focused also belong in their corresponding component's repo. For example, Eventing specific test code is located in the knative/eventing tests folder.

User-focused content

• Documentation: Content for developers or administrators using Knative. This documentation belongs in the knative/docs repo. All content in knative/docs is published to the Knative website.

• Code samples: Includes user-facing code samples and their accompanying step-by-step instructions. Code samples add a particular burden because they sometimes get out of date quickly; as such, not all code samples may be suitable for the docs repo.

  • Knative owned and maintained: Includes code samples that are actively maintained and e2e tested. To ensure content is current and balance available resources, only the code samples that meet the following requirements are located in the code-samples/serving and code-samples/eventing folders of the knative/docs repo:

    • Actively maintained - The code sample has an active Knative team member who has committed to regular maintenance of that content and ensures that the code is updated and working for every product release.

    • Receives regular traffic - To avoid hosting and maintaining unused or stale content, if code samples are not being viewed and fail to receive attention or use, those samples will be moved into the “community maintained” set of samples.

  • Community owned and maintained samples: For sample code which doesn't meet the mentioned criteria, put the code in a separate repository and link to it from this page. These samples might not receive regular maintenance. It is possible that a sample is no longer current and is not actively maintained by its original author. While we encourage a contributor to maintain their content, we acknowledge that it's not always possible for certain reasons, for example other commitments and time constraints.

While a sample might be out of date, it could still provide assistance and help you get up-and-running with certain use-cases. If you find that something is not right or contains outdated info, open an Issue. The sample might be fixed if bandwidth or available resource exists, or the sample might be taken down and archived into the last release branch where it worked.