Technical writing




@docs-team on Slack


Uploading graphics

Adding Images to Google Cloud Storage

If your changes include any images or video, you’ll need to upload to the Google Cloud Storage (GCP) blog bucket before sticking it in your markdown file. However, if the image is less than 100kb in size, it can be added to the /doc folder.

  1. Once you have permissions set up, view the sourcegraph-assets bucket
  2. Make sure your file has a unique name that clearly describes the image or video. There are lots of files in Google Storage, and you want to be able to identify yours easily.
  3. If you’re working on a blog, navigate to the blog/ folder found in the link in step 1. Navigate to the appropriate release folder—if your release folder is missing, go ahead and make a new one.
  4. Click “Upload Files” to select your file, and click “Open”.

Publishing changes

The publishing process for the website, handbook, and docs is the same as the one listed in editing the handbook.

Local previews

Handbook changes

  1. Navigate to your local sourcegraph/about repository
  2. Run make serve to start
  3. Preview at localhost 5082
  4. Ctrl-c will kill the server

Run make docsite-check to verify your changes and catch any broken links.

Product docs

  1. Navigate to your local sourcegraph/sourcegraph repository
  2. Run ./dev/ serve to only run the documentation (vs. starting the Sourcegraph instance)
  3. Preview at localhost 5080

Marketing website or blog

  1. Navigate to your local sourcegraph/about repository
  2. Go into the website sub-directory
  3. Run yarn start
  4. Preview at localhost 8000