add docs to this repo, show them at /help
Created by: sqs
This PR moves product documentation from the sourcegraph/about repo to this repo's doc/
dir (which is the new source of truth for product docs) and adds a /help
area that displays these docs. The goals are:
- Make it easier to keep docs up to date with the code and comprehensive.
- Make it possible to see the docs as of the current product version you are using.
For goal 1: The .md
files in doc/
are as simple as possible. There is no front matter required, and they are browseable on the file system. After this PR is merged, all future PRs to this repo can (and should) now include all relevant docs updates.
For goal 2: This PR also adds a new help area to the product at /help
. This shows the docs as of the commit that the app was built from. Users of Sourcegraph instances can browse these docs to get docs on their current version.
After this PR is merged, I will follow up with more updates to the docs and the process for updating them (to ensure PRs contain doc updates when necessary). Those are not blockers for getting this PR merged, and it's better to get this merged sooner so that docs aren't in a weird limbo of "about to be moved from one repo to another" (which creates confusion).
See these repos for more info:
- The doc generator tool: https://github.com/sourcegraph/docsite (used as the HTTP server for docs.sourcegraph.com and used as a library by sourcegraph/sourcegraph)
- Templates and assets for https://docs.sourcegraph.com: https://github.com/sourcegraph/docs.sourcegraph.com
The diff is big primarily because this PR copies all doc files from the about repo here.
TODOs (can review before I address these):
-
Remove any other unused gif/png/svg files from doc/
to avoid enlarging the Git repo unnecessarily -
Ensure that the dist
build tag properly bundles in the current product version docs
This PR updates the CHANGELOG.md file to describe any user-facing changes. This PR does not need to update the CHANGELOG because ...