Internal Errigal Collaboration Wiki

User Tools

Site Tools

Trace: • troubleshooting_-_address_details_not_updating_after_spreadsheet_upload • watchdog_resolutions • updatinguserguides
userguidesanddocumentation:updatinguserguides

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
userguidesanddocumentation:updatinguserguides [2021/08/26 12:47] – 10.91.120.28userguidesanddocumentation:updatinguserguides [2021/11/23 11:34] (current) – 10.91.120.28
Line 29: Line 29:
 ---- ----
  
-===== User Guide Tracker Sheet =====+===== Deploying For A Release =====
  
-The User Guides Tracker sheet is used to provide a high-level overview of the user guides that have been updated in each sprint. User guides that are updated outside of a sprint are simply noted under the current active sprint.+  * Deployments are done via [[http://jenkins.errigal.com:8080/login|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.
  
-It is also used as a guide to determine what user guides are necessary for each customer:+**Deployment Parameters:**
  
-  * ATC - American Tower +  * **Generate** - Generate documents as part of this Jenkins job - YES/NO 
-  * EXT - ExteNet +  * **Deploy** - Deploy documents as part of this Jenkins job? - YES/NO 
-  * NCS - Non-Customer Specific +  * **Format** - The format to generate - PDF/HTML - Select PDF unless specified otherwise 
-  * KLA - KLA (This customer will get a copy of the NCS version of user guides) +  * **Docs** - Type of documents to deploy - Release-Notes, Supplemental-Documentation, User-Guides 
-  * SCO - SCO (This customer will get a copy of the NCS version of 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
  
-The link to the User Guides Tracker sheet is here:  +**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.
- +
-[[https://docs.google.com/spreadsheets/d/1AFtHjIyrUI8AT5TGDkoHXs1bnMdTjTLt-ucztAry75c/edit#gid=270445129|User Guides Tracker Sheet]] +
- +
-With future changes to the version control of the doc generation repo, this sheet will no longer be necessary (TBD)+
  
 ---- ----
Line 51: Line 55:
 ===== Updating A User Guide ===== ===== Updating A User 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. +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).
- +
-Here are the steps to update a user guide: +
- +
-**1. Pull the repo and perform your updates:** +
- +
-  - Pull the latest version of the document generation repo linked here: [[https://bitbucket.org/errigal/errigal-document-generation/src/master/|https://bitbucket.org/errigal/errigal-document-generation/src/master/]] +
-  - Install **Typora** for editing markdown if you haven't already and open up the entire document generation folder to navigate to the user guide you need to update. +
-  - 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. +
-  - Once your document is open, perform any necessary updates +
-  - 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 & HTML versions of the user guide:** +
- +
-  - With your update complete, it's time to generate a PDF & HTML version of the user guide for each relevant customer. +
-  - To determine the relevant customers for a user guide, consult the [[https://docs.google.com/spreadsheets/d/1AFtHjIyrUI8AT5TGDkoHXs1bnMdTjTLt-ucztAry75c/edit#gid=270445129|User Guides Tracker Sheet]] +
-  - 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. +
-  - Next, open a command prompt and navigate to the document generation directory. +
-  - From here run the necessary commands to generate both an HTML & 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. +
-  - 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:** +
- +
-  - After updating the user guide & generating the relevant docs, it's time to commit & push the changes. +
-  - Include in the commit message the relevant Ticket ID as well as the name of the user guide being updated. +
-  - 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. +
-  - 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:** 
  
-  - This can be manually done via the Support Page by uploading the file etc. More detail on that process can be found here: [[development:applications:supportpage:userguides|IDMS Support Page - User Guides]] 
-  - Alternatively, you can use the [[http://wiki.err/doku.php?id=toolsandtechnologies:jenkins_2|Jenkins]] project which automates the deployment. 
-  - 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: no (keep this as no for now as we can't generate documents yet) 
-  * 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) 
  
-  - Select **Build** once you're happy with the selections 
-  - Make sure the process is done and no failures from Jenkins are there 
-  - Navigate to the Support Page instance and verify the files were deployed correctly 
userguidesanddocumentation/updatinguserguides.1629978428.txt.gz · Last modified: 2021/08/26 12:47 by 10.91.120.28

Page Tools

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki