(#1021) Provide clarity to choco sync command

We get a lot of questions about how to run `choco sync` and this commit provides clarity on how the command works, recommended and alternate usage guidance, and a callout at the top of the page to alert users to the power of the command itself.

Author: imm0rtalsupp0rt

src/content/docs/en-us/features/package-synchronization/sync-command.mdx

@@ -8,96 +8,65 @@ import Callout from '@choco-astro/components/Callout.astro';
 import Iframe from '@choco-astro/components/Iframe.astro';
 import Xref from '@components/Xref.astro';
 
-## Sync Command
-
-Starting in 1.9.0 of the licensed extension, sync has been added as a preview feature for organizations to try out. Currently Business edition only, but expected to be in Pro+ at some point - check https://chocolatey.org/compare#compare for availability.
-
-Sync looks at all software that is in Programs and Features that is not being managed with Chocolatey packages and brings them under management. This means you can run one command and suddenly, all of the software installed on a machine is under management by Chocolatey!
-
-### Usage
+<Callout type="danger">
+    This feature requires following specific instructions for its recommended use. Please read this documentation before running the `choco sync` command.
+</Callout>
 
-To synchronize your system, Simply call `choco sync` and Chocolatey will ensure that all software in Programs and Features comes under Chocolatey management and provides you the packages/package sources so you can add them to source control for managing those packages over time.
+## Summary
 
-#### Setup
+When running `choco list --include-programs`, a list of additional applications can be seen at the end of the output that are not managed with Chocolatey.
 
-At 1.9.0, sync is in preview. You need to turn it on by enabling the feature  `allowPreviewFeatures`:
+Running the `choco sync` command allows Chocolatey to reference the registry keys for those additional applications in Programs and Features that are not being managed with Chocolatey, automatically generate a package, and then map the application to that package and bring it under Chocolatey's management.
 
-* `choco feature enable --name allowPreviewFeatures`
+**Use of the `choco sync` command is only available with a Chocolatey for Business (C4B) license.**
 
-### See it in action
+Syncing software can be tricky because the name of the _package_ is what Chocolatey uses for management, not the name of the _application_. For example, the package for Google Chrome on the <a href="https://community.chocolatey.org/packages" target="_blank" rel="noopener noreferrer">Chocolatey Community Repository (CCR)</a> is named `GoogleChrome`, but running `choco  sync` without any options would create the package and name the package `google-chrome`. This is because Chocolatey provides a hyphen or dash (`-`) to resolve any spaces in the name of the application being synced.
 
-We've prepared a short video to show sync in action:
+As a result, while the `GoogleChrome` package from the Chocolatey Community Repository and the `google-chrome` package generated by running `choco sync` without options contain the same application, Chocolatey respects them as _two separate packages_ due the difference in their _package names_. This is why recommended practice is to use the listed options `--id` and `--package-id` to directly map the application to the wanted package name instead of allowing the package name to be created by Chocolatey without user input.
 
-[![Chocolatey's Package Synchronizer - Sync Command](https://img.chocolatey.org/docs/features/sync-command-video.png)](https://youtu.be/tzSsYHYsjf4 "Chocolatey's Package Synchronizer - Sync Command")
+### Recommended Use
 
-<Callout type="info">
-    To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b.
-</Callout>
+To synchronize your system to allow future management with packages from the Chocolatey Community Repository (CCR):
 
-In the following image, sync is run on a system that has 18 applications installed and a base Chocolatey for Business install. Note after running sync, all software on the machine is now being managed by Chocolatey.
+1. Search for the packages on the Chocolatey Community Repository that correspond with the software that you have listed in Programs and Features.
+2. Open an administrative PowerShell session and run `choco sync --id='SOFTWARE_NAME_IN_PROGRAMS_AND_FEATURES' --package-id='PACKAGE_NAME_FROM_CCR'` to map the software directly with the correct package ID.
+3. Chocolatey will create the package for the software in Programs and Features. After creation, the package is placed in the `C:\Users\$USERNAME\sync` folder by default, where you can retrieve them and push them to your internal repository. If you specified a directory with the `--output-directory` option, the package will be placed there instead.
 
-![Chocolatey's Package Synchronizer Sync Command - if you are on https://docs.chocolatey.org/en-us/features/package-synchronization, see commented html below for detailed description of image](https://img.chocolatey.org/docs/features/features_choco_sync.png)
+### Alternate Use
 
-{/*
-Text in the image above:
+To synchronize your system to allow internal management only, open an administrative PowerShell session and run `choco sync` and Chocolatey will automatically create and name packages for all software in Programs and Features. These packages are placed in the `C:\Users\$USERNAME\sync` folder by default, where you can retrieve them and push them to your internal repository. If you specified a directory with the `--output-directory` option, the package will be placed there instead.
 
-Package Synchronizer's Sync Command
+### Additional Considerations
 
-- Brings unmanaged software under Chocolatey management
-- Provides you the source packaging and package output
-- Automate existing systems in under 90 seconds!
-- Machine parseable with `-r`
-- Links existing packages not tracking to Programs and Features
+It is not recommended to run `choco sync` continually over time, such as through a scheduled task or a Chocolatey Central Management deployment. The command is designed to be used once to create a package for an application already installed to remove the need to create that package from the ground up, and going forward, applications should be managed with Chocolatey packages.
 
-This image shows running `choco sync`. It shows first a system that has 18 applications installed outside of Chocolatey, then runs `choco sync` and watches Chocolatey generate packages and baseline the system. Then it shows `choco list -lo --include-programs` again, which shows that all software on the machine is now being managed by Chocolatey.
+When you use `choco sync`, there may be additional work necessary to make the generated packages viable depending on the type of installer the software uses.
 
-*/}
+Software installed from an MSI will sync without the need to make further changes. Software installed from an `exe`-based installer, such as `setup.exe`, will need the original installer placed in the `tools` directory inside the package, and the silent arguments for installation will need to be added to the `chocolateyInstall.ps1` which can also be found in the `tools` directory inside the package.
 
-### Options and Switches
+## Options and Switches
 
 The following are available in the <Xref title="choco sync" value="choco-command-sync" /> command.
 
 ```
-     --id=VALUE
+--id=VALUE
      Id - The Display Name from Programs and Features
 
-     --out, --outdir, --outputdirectory, --output-directory=VALUE
+--packageid, --package-id=VALUE
+     PackageId - When used with Id, this will be the custom name for the
+       package. Business editions only.
+
+--out, --outdir, --outputdirectory, --output-directory=VALUE
      OutputDirectory - Specifies the directory for the generated Chocolatey
        package file(s). If not specified, uses a subdirectory of the current
        directory.
-```
-
-### FAQ
-
-#### How do I take advantage of this feature?
-
-You must have the [business edition of Chocolatey](https://chocolatey.org/pricing). Business editions are great for organizations that need to manage the total software management lifecycle.
-
-#### I'm a business customer, now what?
 
-You would periodically run `choco sync`.
-
-#### How does it work?
-
-Chocolatey takes a look at all software in Programs and Features that is not under Chocolatey management, generates packages on the fly and baselines them under the Chocolatey install, ensuring all of the links are tracked.
-
-#### Do I get the packages to add to source?
-
-Yes! Chocolatey will tell you the location of the sync files so you can put them into source control.
-
-#### Some packages have a TODO list
-
-Generating packages on the fly from Programs and Features for non-MSI installers doesn't provide everything necessary to ensure an actual install. So when you take those packages back to source, you will need to finish out the packaging for those so that later when you upgrade, things will work appropriately.
-
-#### How do I get machine parseable output?
-
-Use `-r`. `choco sync -r`.
-
-#### What if I have an existing package that is just not tracking to Programs and Features?
-
-Synchronize can recognize existing packages and sync to those as long as the name of the package is a close match to the software name (e.g. Google Chrome becomes either google-chrome or googlechrome).
+ -r, --limitoutput, --limit-output
+     LimitOutput - Limit the output to essential information. This provides machine parsable output.
+```
 
-### Sync Command Known issues
+## Sync Command Known Issues
 
 * Any packages you've installed side by side (`-m`) will show up every time during sync.
-* If you have both a 64-bit and 32-bit version of some software installed, sync will track to one on the first run and the other on the next run. This is not a normal scenario.
+* If you have both a 64-bit and 32-bit version of some software installed, sync will track to one on the first run and the other on the next run. This is not a normal scenario.
+* If uninstalling a package created from running `choco sync`, the uninstall may not be silent, causing the auto uninstaller to fail. This may or may not result in the package being removed.