Rewrite collaboration document

docs/collaboration.md

@@ -4,63 +4,96 @@
 publish content to Posit Connect using
 [Visual Studio Code](https://code.visualstudio.com/) and
 [Positron](https://positron.posit.co/)—enables seemless collaboration. This
-workflow guide shows how to collaborate with others on a piece of content.
+workflow guide explains how to collaborate with others on a deployed piece of
+content.
 
-## Initial setup
+## Deployment and Configuration files
 
-To ensure that others can collaborate without issue the deployment and
-configuration files should be available.
+Posit Publisher creates and utilizes two files for deploying content. Both are
+inside of the `.posit/publish` directory in the same directory as
+your entrypoint file.
 
-That means including them in the repository for the project or including them
-in the `files` attribute in the configuration so they are available in the
-content bundle.
+The first is the Configuration file which describes how the content will be
+deployed to Posit Connect.
 
-When Posit Publisher creates a configuration it has the deployment and
-configuration files included for deployment.
+An example of a Configuration file is `/.posit/publish/content-title-061E.toml`.
 
-The inclusions are in the `files` list and look like:
+The second is the Deployment file which contains details on where the content
+was deployed and its state. Deployment files are automatically generated by
+Posit Publisher and update during deploys.
 
-- `/.posit/publish/deployments/deployment-58A3.toml` for the deployment file
-- `/.posit/publish/content-title-061E.toml` for the configuration file
+An example of a Deployment file is
+`/.posit/publish/deployments/deployment-58A3.toml`.
 
-The inclusion of the deployment and configuration files allows others to easily
-collaborate when they use the Source Version content bundle as a starting point.
+Utilizing both of these files, alongside a credential and collaborator access
+on Posit Connect, you and your collaborators can update and configure a single
+piece of content.
 
-## As a collaborator
+### Collaborator access
 
-### Start from a repository
+The original creator of a piece of content on Posit Connect needs to give others
+the collaborator permissions to update the content.
 
-Clone the repo
+See the [Posit Connect User Guide - Access list settings](https://docs.posit.co/connect/user/content-settings/#set-collaborators)
+documentation for more information on giving users access to update a piece of
+content.
 
-### Start from a content bundle
+## Source control setup
 
-Download the Source Version content bundle. If .posit files are included.
+Deployment and Configuration files found in `./posit/publish` are intended
+to be committed into source repositories.
 
-They are included by default
+Once tracked in source control, anyone with access can easily collaborate on the
+same piece of content.
 
-See the
-[Posit Connect User Guide - Source Versions](https://docs.posit.co/connect/user/source-versions/)
-documentation for more information on how to download the content bundle.
+After a deploy be sure to commit any changes to the Deployment and Configuration
+files. Keeping them in sync with the content on Posit Connect will ensure that
+collaborators have the most up-to-date details to continue where others left
+off.
 
-Callout note about how this only includes deployed files.
+## Content bundle setup
 
-### First time deploying
+If you and your collaborators aren't using source control, a content bundle
+containing the source code and data for a piece of content can be downloaded
+from Posit Connect. Content bundles are created when content is published and
+they work great with Posit Publisher.
 
-If the deployment is pointed to a server that you have not deployed to before,
-you may need to setup your credentials.
+When deploying, include the Deployment and Configuration files so others can
+use them to collaborate after they download the content bundle.
 
-Posit Publisher makes this easy by prompting you to _Create a new Credential_
-when the selected deployment requires a credential you don't have.
+Posit Publisher includes both files automatically in configurations it generates
+to make this effortless.
+
+See the
+[Posit Connect User Guide - Source Versions](https://docs.posit.co/connect/user/source-versions/)
+documentation for more information on the content bundle source versions and
+how to download them.
 
-TODO: SCREENSHOT
+> [!NOTE]
+> The content bundle will only contain files sent to Posit Connect. Be sure any
+> files that you would like collaborators to have access to are in the
+> Configuration's included `files`.
+> For more details see the [Project Files documentation for Posit Publisher](./vscode.md#project-files).
 
-## While collaborating
+## Tips
+
+### Stay updated while collaborating
 
 While collaborating on a piece of content, stay updated with the latest changes
 others have made.
 
-To do so, pull down the latest changes from the repository or download the
-content bundle from the latest Source Version on Posit Conect.
+To do so, either pull down the latest changes from the repository or download
+the content bundle from the latest Source Version on Posit Conect.
 
 Doing so ensures that you have the most up-to-date content, but also
 configuration settings and deployment details.
+
+### First time deploying
+
+If a deployment is pointed to a server that you have not deployed to before,
+you may need to setup your credentials.
+
+Posit Publisher makes this easy by prompting you to _Create a new Credential_
+when the selected deployment requires a credential you don't have.
+
+TODO: SCREEN SHOT