microsoft / qsharp-language

Official repository for design of the quantum programming language Q# and its core libraries
MIT License
235 stars 56 forks source link

Process for adding or removing pages in language docs is unclear #151

Open bamarsha opened 2 years ago

bamarsha commented 2 years ago

To get the language docs to show up in the user guide at https://docs.microsoft.com/en-us/azure/quantum/user-guide/, there are stubs and a UID mapping defined for each page here: https://github.com/MicrosoftDocs/quantum-docs/tree/main/articles/user-guide/language

However, if pages are added or removed, the stubs don't seem to be updated automatically. It's not clear to me what the process is for updating them and it doesn't seem to be described in this repo. I think it would be better to:

bamarsha commented 2 years ago

@bettinaheim do you have any thoughts on the process and how to prevent the docs repo from becoming out of sync?

bamarsha commented 2 years ago

And just to clarify/rephrase, but my understanding of the situation is:

  1. To update the contents of existing pages, only this repo needs to be changed.
  2. To add, remove or rename pages, both this repo and quantum-docs need to be changed simultaneously.

IMO this split is kind of weird, and ideally I'd prefer everything to be done all in one repo. Or it would be nice if it was clearly documented and checked in CI for the second case.