Audit technical documentation for accuracy and completeness

[MelissaBraxton]

Acceptance criteria

• [x] We have confirmed that technical documentation is accurate and up to date

Tasks

• [x] Verify release process documentation is up to date
• [x] Ensure that our applications and services are using appropriate authentication credentials
• [x] Ensure that our CI/CD pipelines are documented, well understood, and 2+ people have access
• [x] Detailed, accurate instructions for adding a new permit type and required changes to the middle layer are findable on GitHub
• [x] Existing README documentation on how to set up the environment is up-to-date
• [x] Ensure that the third party services contacts wiki page is up to date

Definition of done

• [x] Meets acceptance criteria

[mgwalker]

@carlsonem Do you know who would know where some of this documentation is and whether it's up-to-date? Especially the release process, CI/CD pipeline, and instructions for a new permit type (which might in fact be a very big ask). The others I can find and check on myself.

[carlsonem]

@mgwalker it will be in a variety of places, lots of it will be on our wiki or in the GHE repo.

https://github.com/USDAForestService/fs-open-forest/wiki/DevSecOps-Implemented https://github.com/USDAForestService/fs-open-forest/wiki/Ongoing-site-architecture

Not sure what you mean by instructions for a new permit type, can you elaborate what you are looking for?

[mgwalker]

I'm not sure what that one means either. It's in the acceptance criteria, though. I assume it's about extending the Open Forest platform to support additional permit types in the future, on the assumption that it was built to easily add them. Maybe @MelissaBraxton can clarify?

[MelissaBraxton]

Apologies! I didn't see this while I was out. @mgwalker has it right!

[MelissaBraxton]

Also take a look at https://github.com/USDAForestService/fs-open-forest-platform Some of the instructions there (e.g. building the site locally) may be out of date.

[mgwalker]

• [ ] deployment process documentation only discusses dev. We need to also capture what conditions trigger a merge to staging and prod. This relates to the release documentation requirement above.
  • On this point, AFAIK there's not a defined trigger to updating staging and prod, so it might be time to create those. It could be time-based (e.g., weekly on Tuesdays), feature-based (e.g., everyone has signed off on all the issues that are currently in dev, so merge it to staging), or something else. But we need something so everyone knows when to expect updates to happen. That should ease some of the onboarding anxiety when we get a new product owner too.
• [ ] the site architecture diagram needs to be updated to include the link to NRM TIM
• [ ] the page about debugging common dev problems refers to CircleCI a lot, but it's about Christmas Tree on-call monitoring. Is this section relevant at all any more?
• [ ] need documentation about adding new permit types

@mwreiss Do you know who holds the authentication credentials for cloud.gov and Pay.gov? If so, can you verify that those are setup appropriately? (I.e., cloud.gov is using a deployer account rather than an individual's credentials. Pay.gov is using whatever secrets it's supposed to use?) I suspect this is all in good shape, but just need to double-check.

@mwreiss Also, do you know if the Christmas Tree on-call monitoring section is still relevant? Should that whole chunk get wiped out?

@mtlaney How would you feel about trying to work this issue in as a dev ticket for next sprint? I could handle the first one once there's a decision about what the process should be (maybe a quick 10 minutes with the whole team at the end of standup one day?). I think the biggest issue will be the last one, documenting how to scale up with additional permit types.

[mgwalker]

@mwreiss Oops, meant to tag you one more time in the last one. For the updated system diagram, do you have anything sitting around already? If not, I can take a crack at recreating it (since I don't have the original).

[carlsonem]

@mwreiss

[mwreiss]

Documentation was addressed and updated during the Q1 security testing. This is complete