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.

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 the user guide, and deploy it to the support page yourself.

Here are the steps to update a user guide:

1. Pull the repo and perform your updates:

1. Pull the latest version of the document generation repo linked here: https://bitbucket.org/errigal/errigal-document-generation/src/master/
2. Create a new branch to store your changes (if the changes are made outside of a sprint, otherwise use the sprint-related branch).
3. Install Typora for editing markdown and open up the folder to navigate to the user guide you need to update.
4. Navigate to the inputs directory to find the user guide to update. Inputs are divided into User Guides, Release Notes & Supplemental Documentation in line with the Support Page setup.
5. Once your document is open, perform any necessary updates
6. Note: some documents contain customer-specific embedded files, these are denoted with something like: [NCS|./NCS/00-EMS-Overview.md]. If you cannot find what you are looking for in the main document, it may be in an embedded file.

2. Generate the PDF versions of the user guide:

Note: This step isn't required unless you would like an immediate copy of the guide. The Jenkins job will generate and deploy the guides so it's not necessary.

1. With your update complete, it's time to generate a PDF version of the user guide for each relevant customer.
2. To determine the relevant customers for a user guide, consult the User Guides Tracker Sheet
3. Look for the user guide on the Master Sheet tab and the associated customers will be next to it. For example: the EMS UG requires copies for ATC, EXT, NCS (KLA, SCO) - in this case, KLA & SCO will receive a copy of the NCS guide but we generate them separately into each customer folder to make deployment easier.
4. Next, open a command prompt and navigate to the document generation directory.
5. From here run the necessary commands to generate the PDF version of the user guide for each relevant customer. More detail on this is found in the Code Usage section of the repo's Readme file.
6. Here's an example snippet that generates an ATC PDF version of the AmCharts document:

python3 generate-documents.py -g pdf -e ATC -i inputs/Supplemental-Documentation/AmCharts-4-SD/AmCharts-4-SD.md -o outputs/ATC/Supplemental-Documentation/

3. Push the changes and generate a pull request:

1. Include in the commit message the relevant Ticket ID as well as the name of the user guide being updated.
2. Next, create a pull request and be sure to include Michelle so she can review the changes to confirm they are in line with Errigal standards, etc.
3. Once the pull request has been approved and the changes have been merged into the repo, the next step is to deploy the user guide to the relevant Support Page instance.

4. Deploy the user guide update to the Support Page:

1. This can be manually done via the Support Page by uploading the file etc. More detail on that process can be found here: IDMS Support Page - User Guides
2. Alternatively, you can use the Jenkins project which automates the deployment.
3. The Jenkins project is called Errigal Support Documentation. Open the project and select the option Build With Parameters.

You should be presented with the following set of dropdowns:

• GENERATE: yes
• DEPLOY: yes (we want to deploy so set this to yes)
• FORMAT: pdf (the format of documents to deploy)
• DOCS: User-Guides (this denotes the documents to be deployed: User Guides, Release Notes, or Supplemental Documentation to correspond with the Support page setup)
• CUSTOMER: NCS (customer to deploy the documents to)
• ENV: IRONMAN (select the correct environment)
• AUTHOR: ERRIGAL (Enter your own name to track the changes)

1. Select Build once you're happy with the selections
2. Make sure the process is done and no failures from Jenkins are there
3. Navigate to the Support Page instance and verify the files were deployed correctly