A documentation package is the grouping mechanism for all documentation (rich text notes, images, url links and process diagram links) created for your Org model metadata.
For each package you can create multiple versions. The version files are what actually carries over the documentation and can be imported into the target Org. The same package can have many different versions which contain completely different set of documents.
A documentation package version contains information on the documentation itself and also on the metadata source item. When importing a version of a package to an Org model, the system is first trying to find metadata with a matching API name. If found, it creates an attachment. If the target Org model has all the same metadata as the source Org model, then after import they will share the same documentation.
You can create multiple versions of the same documentation package. This is especially useful for ISVs who constantly evolve their managed packages. You can update the documentation for each new version of your managed package.
A client can only have one version of the same documentation package installed in their Org model at a time. If they install a different version of the same documentation package then that new version will replace the old version and associated documentation.
This logic is explained below:
Let’s assume that in the process of installing version 1 of the documentation package you imported 3 attachments: A1, B1 and C1.
If you edit/update an attachment which came from the documentation package then you effectively make it a local attachment and you remove any linkage between that attachment and its package of origin.
Let’s now imagine that you install a new version of the documentation package (version2). In a hypothetical scenario outlined above:
To include diagrams in your documentation packages you need to:
When the client imports a package version which includes diagram links: