Technical writing

Vision

TODO

Contact

@docs-team on Slack

Process

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 -If you don’t have permission to view the contents of this link, ask the team in #it-tech-ops for Google Cloud Storage permissions to add images to the Handbook.
  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. If you’re adding an image or video to Handbook documentation, navigate to the handbook/ folder found in the link in step 1.
  5. Click “Upload Files” to select your file, and click “Open”.

Adding Images from Google Cloud Storage to the Handbook

  1. In Google Cloud Storage, copy the URL for the image you want to include.
    • You can do this by clicking the file name to see more details, then copying the “Public URL”.
  2. To insert your image into the Handbook, follow this format:
    • ![Alt Text](Image URL)
  3. Finish editing and merge your changes as normal

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/docsite.sh 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