Docs UX improvements tracking issue

Created by: dadlerj

Reposted from Slack:

I have some concerns about our docs update-ability and navigation.

I’m noticing that in order to add or move a page, I have to go manually update a bunch of different indexes — doc.html (i.e., the sidebar), the top-level index, and all sub-section indexes, if relevant.

And I see a number of instances where people just haven’t done that, and the nav has gotten pretty inconsistent — e.g., from the site-admin (docs.sourcegraph.com/admin) doc section, on the left sidebar I see “External services”, but they don’t appear anywhere on the index page. There IS an “Integrations” section there, but those actually link out to an entirely separate top-level section (docs.sourcegraph.com/integrations).

@ryan-blunden is there a long-term plan to keep updating our docsite generator, or is it more of a temporary holdover until you have bandwidth to reevaluate outside options?

Specific requests:

• Autogenerating the sidebar and index files based on folder structure (and keeping them consistent — the sidebar’s organization in the screenshot above being different from the index page is a bit confusing).
• Thinking holistically about what the right folder structure is (who are we optimizing for)?
• Having a CODEOWNERS concept in the docs, where each doc file/folder is owned by someone
• Having a step in CI that confirms no broken docs links (both in the docs themselves, AND in the main repo linking out to them given we do that quite a bit)