For consistency throughout the documentation, it’s important to maintain the same structure among the docs.
Before getting started, read through the following docs:
Every document should include the following content in the following sequence:
For additional details, see the subsections below, as well as the Documentation template for new docs.
Every major feature should have, at the beginning of the document, two main sections: Overview and Use cases.
Overview: as the name suggests, the goal here is to provide an overview of the feature. Describe what is it, what it does, why it is important/cool/nice-to-have, what problem it solves, and what you can do with this feature that you couldn’t do before.
Use cases: provide at least two, ideally three, use cases for every major feature. You should answer this question: what can you do with this feature/change? Use cases are examples of how this feature or change can be used in real life.
Note that if you don’t have anything to add between the doc title (
<h1>) and the header
## Overview, you can omit the header, but keep the content of the overview there.
The overview and use cases are required for every Enterprise feature, and for every major feature present in OSS.
Your new document will be discoverable by the user only if:
To start a new document, respect the file tree and file name guidelines, as well as the style guidelines. Use the following template:
--- description: "short document description." # Up to ~200 chars long. They will be displayed in Google search result previews. --- # Feature name > [Introduced](link) in Sourcegraph X.Y. A short description for the feature (can be the same used in the frontmatter's `description`). ## Overview To write the feature overview, you should consider answering the following questions: - What is it? - Who is it for? - What is the context in which it is used and are there any prerequisites/requirements? - What can the user do with it? (Be sure to consider multiple audiences, like Sourcegraph site admins and regular users.) - What are the benefits to using it over any alternatives? ## Use cases Describe one to three use cases for that feature. Give real-life examples. ## Requirements State any requirements, if any, for using the feature and/or following along with the tutorial. The only assumption that is redundant and doesn't need to be mentioned is having an account on Sourcegraph. ## Instructions ("Instructions" is not necessarily the name of the heading) - Write a step-by-step guide, with no gaps between the steps. - Start with an h2 (`##`), break complex steps into small steps using subheadings h3 > h4 > h5 > h6. _Never skip the hierarchy level, such as h2 > h4_, as it will break the TOC and may affect the breadcrumbs. - Use short and descriptive headings (up to ~50 chars). You can use one single heading `## How it works` for the instructions when the feature is simple and the document is short. - Be clear, concise, and stick to the goal of the doc: explain how to use that feature. - Use inclusive language and avoid jargons, as well as uncommon and fancy words. The docs should be clear and easy to understand. - Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me"). - Always provide internal and external reference links. - Always link the doc from its higher-level index. <!-- ## Troubleshooting Add a troubleshooting guide when possible/applicable. -->