Refactor enterprise documentation #9268
Conversation
ntrogh
requested review from
Copilot and
joshspicer
and removed request for
Copilot
|
@joshspicer I've refactored the existing enterprise docs. Can you give it a review and let me know if there's anything missing, and if the structure and naming makes sense to you? The enterprise policies article is generated automatically when we publish the docs, based on the policies available in the vscode repo. |
ntrogh
changed the title
docs/enterprise/policies.template.md
Outdated
|
|
||
| #### Step 1: Obtain the sample policy file | ||
|
|
||
| The sample `policy.json` file is included with each VS Code release. You can obtain it from either an existing installation or by downloading and extracting the VS Code archive. The file is located in the `resources/app/policies` directory. |
There was a problem hiding this comment.
I might have missed this previously, but other sections specify the release version for the sample in this format (should be 1.106 for linux):
Tip
Starting from VS Code version 1.99, each release ships with a sample .mobileconfig file in this location.
There was a problem hiding this comment.
Good catch. Also included for Linux
| > [!IMPORTANT] | ||
| > If there's a syntax error in the policy value, the `extensions.allowed` setting is not applied. You can check the Window log in VS Code for errors (press `kb(workbench.action.showCommands)` and enter **Show Window Log**). |
There was a problem hiding this comment.
This is true for any of the policies (the JSON-based ones are specifically vulnerable to misconfiguration though. Is there a more global spot to highlight this fact (in addition to here)?
There was a problem hiding this comment.
I've included it in the policies doc in the section about configuring string values.
docs/enterprise/policies.md
Outdated
|
|
||
| VS Code has support for [Windows Registry-based Group Policy](https://learn.microsoft.com/previous-versions/windows/desktop/policy/implementing-registry-based-policy). Starting from VS Code version 1.69, each release ships with a `policies` directory containing ADMX template files that define the available policies. | ||
|
|
||
| ### Configure policies using Local Group Policy Editor |
There was a problem hiding this comment.
Would be it be possible to convey somehow that these manual steps for Windows/macOS are really only useful for testing? Emphasize that 'real' deployments use some MDM solution/Intune/etc....
I've always felt these docs focused too much on the testing case and, if I was an org admin not super familiar with MDM, would be a bit lost
There was a problem hiding this comment.
I see Deploy policies at scale. I feel like that should higher in this doc and the rest of this file is 'if you'd like to test locally, here are the steps.
There was a problem hiding this comment.
I updated the text to include manual steps. I've also changed the order and made the deployment option (scale/manual) as collapsible sections.
| ### Configure policies using Local Group Policy Editor | |
| These profiles can be deployed using Mobile Device Management (MDM) solutions or installed manually on individual devices. |
joshspicer
left a comment
joshspicer
left a comment
There was a problem hiding this comment.
This is fantastic - thanks so much for the care and attention to detail @ntrogh
Provided some minor suggestions
Co-authored-by: Josh Spicer <[email protected]>
|
@pwang347 @joshspicer I implemented the requested changes. Can you give it another quick review? |
maxine-yx
left a comment
maxine-yx
left a comment
There was a problem hiding this comment.
Overall, this is a well-executed refactoring of the enterprise documentation. The new structure with dedicated pages for policies, AI settings, telemetry, updates, and extensions will make it much easier for enterprise users to find relevant information. All the link updates are consistent and correct.
Create a dedicated Enterprise node in the table of contents. Split the existing enterprise article into dedicated articles per topic.