Improve how to deploy a collection #172
Conversation
✅ Deploy Preview for open-terms-archive-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Ndpnt
force-pushed
the
improve-deployment-doc
branch
from
957fb8a to
8033aec
Compare
There was a problem hiding this comment.
These look like really good improvements to me!
I am just a bit concerned with our respect of Diataxis: I wonder if these “how-to guides” don't go a bit too far and integrate reference or explanation elements.
Regarding the “Specific to Open Terms Archive organization members" parts, I feel that the best way to handle them would be to describe these steps in a generic way, such as “back up this key in a secure way as per your organization's procedures”, and we would have our own internal reference in the cloud.
| ## Understanding the validation | ||
|
|
||
| Open Terms Archive validates terms types to ensure consistency and quality across collections. When you encounter a validation error like: | ||
|
|
||
| ```shell | ||
| 1) Service declarations validation | ||
| <service_name> | ||
| valid declaration schema: | ||
| Error: | ||
|
|
||
| data/terms must be equal to one of the allowed values (in entire file) | ||
| ``` | ||
|
|
||
| This means the terms type you're trying to use isn't in the official list of supported types. |
There was a problem hiding this comment.
Should this section really be in a “how-to” guide? 🤔
| data/terms must be equal to one of the allowed values (in entire file) | ||
| ``` | ||
|
|
||
| This means the terms type you're trying to use isn't in the official list of supported types. |
There was a problem hiding this comment.
Is there no way to improve the error message rather than explaining it in documentation?
|
|
||
| This means the terms type you're trying to use isn't in the official list of supported types. | ||
|
|
||
| ## Before going further |
There was a problem hiding this comment.
| ## Before going further | |
| ## Double-check potential synonyms |
content/deployment/how-to/deploy.md
Outdated
| Each collection uses three repositories, `declarations` which contains the terms to track, the engine and deployment configuration, `versions` and `snapshots` which are automatically managed repositories storing versions and snapshots history. | ||
|
|
||
| The deployment process is automated through GitHub Actions. Ansible configures the server and sets up the Open Terms Archive engine. On the server, [PM2](https://pm2.keymetrics.io) is used to start and control the engine. | ||
|
|
||
| When deployed, the engine runs continuously on the server, periodically checking for changes in the tracked terms. When changes are detected, it automatically commits them to the versions and snapshots repositories. When issues occur, email notifications are sent. |
There was a problem hiding this comment.
Shoudln't this be a reference or an explanation?
|
|
||
| - A server with admin access | ||
| - All collections repositories created, if not, see the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}}) | ||
| - At least one declaration added to your collection |
There was a problem hiding this comment.
| - At least one declaration added to your collection | |
| - At least one declaration in your collection (if you created your declaration from the Demo template, one is provided by default) |
There was a problem hiding this comment.
When we use the demo template, all declarations are removed by the first time setup process.
content/deployment/how-to/deploy.md
Outdated
| 5. > _Specific to Open Terms Archive organization members_ | ||
| > Create a new SMTP key in Brevo and name it "<collection_name> collection" | ||
| > Back up the key in the shared password database by creating an entry titled "SMTP Key" in the collection folder and storing the credentials in this entry |
There was a problem hiding this comment.
No, it is used for sending error emails
Improve wording Co-authored-by: Matti Schneider <[email protected]>
There was a problem hiding this comment.
I would appreciate an explanation of how the showIfParam works in order so that you can use it easily. It would also be useful for me to know which url parameter I should use, as an Open Terms Archive team member.
We mentioned in sync highlighting the showIfParam sections, so that you can clearly see what is being added to the page. What do you think?
Co-authored-by: Clément Biron <[email protected]>
No description provided.