Updating & Deploying User Guides

Author: Michelle McCausland

Customer-facing user guides are created for each IDMS application. The aim of these user guides is to assist users when interacting with the IDMS platform to carry out work.

User guides are updated during each sprint in conjunction with each development ticket. These updates are then deployed to the Errigal Support Page during each release. As of IDMS 3.14, the deployment process has been automated via Jenkins (more detail on that in a later section).

More information on the Support Page can be found on the IDMS Support Page section of this wiki.

Any ad hoc updates that fall outside of the sprint are can be carried out as necessary and deployed.

User Guides, Release Notes, and other relevant documents are stored in the following bitbucket repo:

https://bitbucket.org/errigal/errigal-document-generation/src/master/

It's a good idea to read the Readme file at least once to get familiar with the project.

To summarize the function of the repo, user guides are created in a Markdown format and then PDF & HTML versions are generated to be deployed to a support page instance.

We'll look at this in more detail in the next sections of this guide.

• Deployments are done via Jenkins
• Once logged in, open the Errigal Support Documentation project.
• Then select Build With Parameters
• Fill in the parameters (described below) and select Build
  • For a release you'll need to deploy: Release-Notes, User-Guides, Supplemental-Documentation
• Ensure the build runs and completes successfully i.e. all of the build steps are green on the status page.
• Verify the user guides + release notes have been deployed to the correct environment. For example, all NCS user guides will be generated + deployed so some may need to be removed for KLA or SCO etc.

Deployment Parameters:

• Generate - Generate documents as part of this Jenkins job - YES/NO
• Deploy - Deploy documents as part of this Jenkins job? - YES/NO
• Format - The format to generate - PDF/HTML - Select PDF unless specified otherwise
• Docs - Type of documents to deploy - Release-Notes, Supplemental-Documentation, User-Guides
• Customer - Customer version of documents to generate - ATC/EXT/NCS
• Env - Environment to deploy to - see properties.yml in Errigal-Document-Generation repo for more details
• Author - Who made the changes - can leave as ERRIGAL

Customer & Env Note: ATC + EXT are the only customers currently that have their own versions of documents. All other customers (SCO, KLA, Netrio) make use of the NCS (Non-customer specific) versions of documents. This is why only ATC + EXT are listed in the customer section as this determines how the documents are generated.

If you are on the ops team and a support request requires an update to a user guide, for instance, you can now pull down a copy of the repo, perform your updates, generate a PR (include Michelle as an approver).