Sourcegraph documentation guidelines

Contributing to documentation

Whenever a feature is changed, updated, introduced, or deprecated, the pull request introducing these changes must be accompanied by the documentation (either updating existing ones or creating new ones).

The developer who made the code change is also responsible for writing the initial documentation for new features and updating the documentation for changes to existing features. At the pace Sourcegraph evolves, this is the only way to keep the docs up to date.

It’s the responsibility of the Product Manager to ensure all features are shipped with documentation (i.e., that nothing slips through), whether is a small or big change.

We use the monthly release blog post as a changelog checklist to ensure everything is documented.

Naming and linking documentation pages

  1. 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.
  2. Always cross-link to .md files, including the file extension, so that the docs are browseable as-is (e.g., in GitHub’s file browser).
  3. When you create a new directory, always start with an index.md file. Don’t use another file name and don’t create README.md files.
  4. Don’t use special chars and spaces, or capital letters in file names, directory names, branch names, and anything that generates a path.
  5. For large images and other binary assets, upload them to the sourcegraph-assets Google Cloud Storage bucket instead with gsutil cp -a public-read local/path/to/myasset.png gs://sourcegraph-assets/ (and refer to them as https://storage.googleapis.com/sourcegraph-assets/myasset.png).
  6. When creating a new document and it has more than one word in its name, use underscores instead of spaces or dashes (-). For example, a proper name would be import_projects_from_github.md.
  7. Start a new directory with an index.md file.