docs: move files in docs to Wiki (original) (raw)

Background

In microsoft/vscode-go#3168 we moved all the contents from Wiki to the docs directory.

The rationals behind the move were

• GitHub Wiki repo is separate from the regular github repo and does not allow convenient ways of reviewing PRs and inspecting changes. (Wiki: update FAQ, modules support, misc... microsoft/vscode-go#3148).
• We don't want to allow Wiki contents to be editable without proper review process. GitHub restricts search engines' crawling of Wiki contents if the edit permission is not restricted. Permit search engines to index Github wikis community/community#4992 And we've seen Wikis without proper review process often suffering from vandalism or inaccuracy.
• Users without edit permissions cannot easily contribute to the Wiki contents, like other markdown files in the repo using GitHub's Markdown edit/preview feature. So, bar for contribution is high.

With the move, however, we had to give up GitHub's Wiki UI that allows more customization & search &
index options suitable for documentations. Documentation inside the main project repo is not easily
searchable either.

Proposal

Follow the github.com/microsoft/vscode project's wiki page setup. (https://github.com/microsoft/vscode/wiki vs https://github.com/Microsoft/vscode-wiki)

• Maintain the canonical version of wiki pages in vscode-go repo's docs directory.
  • All updates must go through the proper review process.
  • Users can update contents from github's UI and PR workflows.
  • Document autogeneration scripts will continue to work.
• GitHub Action workflow will copy the data in docs directory to github.com/golang/vscode-go.wiki repo.
• Access to github.com/golang/vscode-go/wiki.git is restricted so search engines can crawl them.

Note

1. We may want to move some of user-facing settings/features/tutorials to more publicly visible webpage. Even after then, wiki will continue to serve as a place to host

• internal documentation for project management (triage process, release process, project milestone, contribution guide, etc)
• less polished, transient tips & tricks
• compatibility info
• links to proposals or design docs

cc @golang/tools-team

EDIT: (2022-04-17) Originally I proposed to have a separate repo to host documentation. But that complicates automated documentation generation with which we wanted to maintain consistency between the current code & the settings. Keeping two separate repositories isn't ideal either. Instead, I changed this proposal to use docs directory as the place we keep all the wiki page contents, and mirror the contents to the wiki page.