Add New Documentation

    1. Identify the audience and intended use for the information.
    2. .
    3. Write your contribution following our documentation contribution guides.
    4. Submit your contribution to our .
    5. Follow our review process until your contribution is merged.

    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 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.

    If you need help identifying the audience for you content, we are happy to help and answer all your questions during the biweekly 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:

    Choose a title for your topic that has the keywords you want search engines to find. All content files in Istio are named , but each content file is within a folder that uses the keywords in the topic’s title, separated by hyphens, all in lowercase. Keep folder names as short as possible to make cross-references easier to create and maintain.

    If you want to learn more about how and when your contributions are published, see the section on branching to understand how we use branches and cherry picking to publish our content.