Whenever a feature is changed, updated, introduced, or deprecated, the merge request introducing these changes must be accompanied by the documentation (either updating existing ones or creating new ones). This is also valid when changes are introduced to the UI.
The one responsible for writing the first piece of documentation is the developer who wrote the code. It’s the job of the Product Manager to ensure all features are shipped with its docs, whether is a small or big change. At the pace Sourcegraph evolves, this is the only way to keep the docs up-to-date. If you have any questions about it, ask a Technical Writer. Otherwise, when your content is ready, assign one of them to review it for you.
We use the monthly release blog post as a changelog checklist to ensure everything is documented.
Follow through the documentation structure guide for learning how to structure Sourcegraph docs.
The documentation is organized into the following top-level directories:
admin/for site admins
external_service/for external service-related documentation for site admins (vs.
integration/for the general audience)
extensions/for Sourcegraph extensions
integration/for integrations with other products, targeted at the general audience (vs.
admin/external_service/for site admin-specific docs)
api/for the Sourcegraph GraphQL API
There is no global index or nav, so all docs should be linked from their parent index page. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when it exists.
index.mdfile. Do not use another file name and do not create
-). For example, a proper naming would be
import_projects_from_github.md. The same rule applies to images.
.mdfiles, including the file extension, so that the docs are browseable as-is (e.g., in GitHub’s file browser).
If you are unsure where a document should live, you can mention
@sqs in your
Changing a document’s location is not to be taken lightly. Remember that the
documentation is available to all installations under
/help and not only to
Sourcegraph.com or http://docs.sourcegraph.com. Make sure this is discussed with the
Documentation team beforehand.
If you indeed need to change a document’s location, do NOT remove the old document, but rather replace all of its contents with a new line:
This document was moved to [another location](path/to/new_doc.md).
path/to/new_doc.md is the relative path to the root directory
For example, if you were to move
doc/user/search/query_syntax.md, then the steps would be:
Replace the contents of
This document was moved to [another location](query_syntax.md).
Find and replace any occurrences of the old location with the new one.
Currently there is no automatic linting of documentation files. In the future we may add proselint and markdownlint.
We treat documentation as code, so we’ve implemented some testing:
docsite check: Check that all internal (relative) links work correctly.
To update documentation content, templates, or assets on https://docs.sourcegraph.com, push changes in the
doc/ directory to this repository’s
master branch, then wait up to 5 minutes. Every 5 minutes, docs.sourcegraph.com reloads all content, templates, and assets from
See “Documentation site” for more information.
You can preview the documentation site at http://localhost:5080 when running Sourcegraph in local development (using
enterprise/dev/start.sh). It uses content, templates, and assets from the local disk. There is no caching or background build process, so you’ll see all changes reflected immediately after you reload the page in your browser.
In-product documentation links should point to
/help/PATH instead of using an absolute URL of the form https://docs.sourcegraph.com/PATH. This ensures they link to the documentation for the current product version. There is a redirect (when using either
<a> or react-router
/help/PATH to the versioned docs.sourcegraph.com URL (https://docs.sourcegraph.com/@VERSION/PATH).
We want our written documents to be as up-to-date, accurate, and useful as possible. For this reason, we always prefer creating and using primary documents over secondary documents, such as in the case of documentation, plans, or design docs.
A primary document is a document that is actually used to specify, communicate, or document something to the entire intended audience and is discoverable by that audience. A secondary document is a document that (effectively) only its creator uses or knows about.
Add links to your primary document liberally, from anywhere your audience might be looking!
To choose the right place for your primary document to live, ask yourself:
It’s OK to create secondary documents for your own temporary use. If anybody else would need to use or discover them, transfer the information to the appropriate primary document (and delete the secondary document or clearly mark it as moved).
This is similar to saying “prefer a single source of truth”. The problem with that, however, is that the designated source of truth might be a secondary document such as a technical spec that the intended audience is unaware of. Our use of the term “primary document” is intended to avoid that problem.
Product documentation describes how to use a specific part of the product (e.g., a feature) for users, admins, extension users/authors, API consumers, and integrators. A good product documentation page includes mention of:
Technical articles replace technical content that once lived in the Sourcegraph Blog, where they got out-of-date and weren’t easily found.
They are topic-related documentation, written with an user-friendly approach and language, aiming to provide the community with guidance on specific processes to achieve certain objectives.
A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with Sourcegraph.
They should be placed in a new directory named
/article-title/index.md under a topic-related folder, and their images should be placed in
/article-title/img/. For example, a new article on Sourcegraph organizations should be placed in
doc/user/organizations/article-title/ and a new article on Sourcegraph extensions should be placed in
Suppose there’s a process to go from point A to point B in 5 steps:
(A) 1 > 2 > 3 > 4 > 5 (B).
A guide can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them.
A tutorial requires a clear step-by-step guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B. It does not only describes steps 2 and 3, but also shows you how to accomplish them.
A technical overview is a description of what a certain feature is, and what it does, but does not walk through the process of how to use it systematically.