fix(docs): re-ordered small paragraphs, clarified wording, and added links to tech homepages #531
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Re-ordered tools in monitoring to build conceptually in line with the way each enables the next - Turned first mention of each tool into a link to the relevant docs. Both an ease of reference change and also to disambiguate in the event a name collision exists in the reader's mind. - Clarified relationship between AuthService and Keycloak as this Unicorn initially saw a redundancy and suspected AuthService was perhaps the service IAM solution while Keycloak was the user IAM solution. We could link out to BigBang's explanation of this relationship but I did not: https://docs-bigbang.dso.mil/2.2.0/docs/understanding-bigbang/package-architecture/authservice/ - Wording changes for precision. Example, in MetricsServer, speaking of "container" metrics is more precise (and I believe still accurate) than "cluster" metrics. If it reports on nodes and containers I would (personally) speak of both over the more nebulous "cluster" (which has many more primitives (notably servics and pods) which could be but are not (I think) being reported on). - Most likely errors needing correction: - Metrics Server may be misunderstood - AuthService may be better characterized but I didn't want to plagarize the BigBang docs, and am new to this service.
JoeHCQ1
changed the title
5 tasks
mjnagel
pushed a commit
that referenced
this pull request
Jul 2, 2024
… pr template (#532) As is visible in the `Checklist before merging` section of #531, the markdown link formatting was broken by a second link where only one belonged. Due to the shortness of the CONTRIBUTING.md document, I preferred the link to the doc as a whole over the one which directed to the PR requirements header. ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [X] Other (security config, docs update, etc) ## Checklist before merging - [X] Test, docs, adr added or updated as needed - [X] [Contributor Guide Steps](https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md)(https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md#submitting-a-pull-request) followed
mjnagel
reviewed
Jul 2, 2024
There was a problem hiding this comment.
Appreciate the contribution - few small comments! @UnicornChance may be good to validate for me that nothing changes here with the expected format on the docs site side.
Co-authored-by: Micah Nagel <micah.nagel@defenseunicorns.com>
mjnagel
approved these changes
Jul 2, 2024
UnicornChance
approved these changes
Jul 2, 2024
mjnagel
deleted the
fix/re-order-clarify-and-add-links-to-application-baseline
branch
mjnagel
pushed a commit
that referenced
this pull request
Jul 8, 2024
🤖 I have created a release *beep* *boop* --- ## [0.23.0](v0.22.2...v0.23.0) (2024-07-04) ### ⚠ BREAKING CHANGES * remove emulated gitlab endpoints from keycloak ([#483](#483)) ### Features * identity group auth ([#497](#497)) ([d71d83e](d71d83e)) ### Bug Fixes * **docs:** re-ordered small paragraphs, clarified wording, and added links to tech homepages ([#531](#531)) ([6b2b46b](6b2b46b)) * **docs:** removed double-link which broke the markdown formatting in pr template ([#532](#532)) ([f41ced4](f41ced4)) * **docs:** uds-config.yaml example in k3d-slim-dev README ([#530](#530)) ([2e1c53e](2e1c53e)) * operator retries and error logging ([#511](#511)) ([cae5aab](cae5aab)) ### Miscellaneous * **deps:** update checkout action to latest sha ([#481](#481)) ([c6f0137](c6f0137)) * **deps:** update dependency weaveworks/eksctl to v0.183.0 ([#499](#499)) ([9cb8e4d](9cb8e4d)) * **deps:** update grafana to 11.1.0 ([#380](#380)) ([499058a](499058a)) * **deps:** update istio to v1.22.2 ([#512](#512)) ([dcdadb4](dcdadb4)) * **deps:** update jest to v29.1.5 ([#485](#485)) ([9c392b9](9c392b9)) * **deps:** update neuvector to 5.3.3 ([#467](#467)) ([261057d](261057d)) * **deps:** update pepr to 0.32.2 ([#473](#473)) ([ab4bee9](ab4bee9)) * **deps:** update pepr to 0.32.3 ([#494](#494)) ([2e28897](2e28897)) * **deps:** update pepr to 0.32.6 ([#516](#516)) ([a9d3eec](a9d3eec)) * **deps:** update promtail to 3.1.0 ([#335](#335)) ([4457fce](4457fce)) * **deps:** update uds to v0.12.0 ([#521](#521)) ([8e587ff](8e587ff)) * **deps:** update uds-common tasks to 0.6.1 ([#498](#498)) ([4aa6e33](4aa6e33)) * **deps:** update zarf to v0.35.0 ([#490](#490)) ([86957cf](86957cf)) * docs linting changes ([#505](#505)) ([0fe2015](0fe2015)) * remove emulated gitlab endpoints from keycloak ([#483](#483)) ([495960c](495960c)) * update docs for group auth and readme for docs site ([#540](#540)) ([ace7041](ace7041)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
rjferguson21
pushed a commit
that referenced
this pull request
Jul 11, 2024
… pr template (#532) As is visible in the `Checklist before merging` section of #531, the markdown link formatting was broken by a second link where only one belonged. Due to the shortness of the CONTRIBUTING.md document, I preferred the link to the doc as a whole over the one which directed to the PR requirements header. ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [X] Other (security config, docs update, etc) ## Checklist before merging - [X] Test, docs, adr added or updated as needed - [X] [Contributor Guide Steps](https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md)(https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md#submitting-a-pull-request) followed
rjferguson21
pushed a commit
that referenced
this pull request
Jul 11, 2024
…links to tech homepages (#531) # Summary As a new Unicorn, I made changes which I believe would've increased my comprehension of this document on the first read-through. ## Description - Re-ordered tools in monitoring to build conceptually in line with the way each enables the next - Turned first mention of each tool into a link to the relevant docs. Both an ease of reference change and also to disambiguate in the event a name collision exists in the reader's mind. - Clarified relationship between AuthService and Keycloak as this Unicorn initially saw a redundancy and suspected AuthService was perhaps the service IAM solution while Keycloak was the user IAM solution. We could link out to BigBang's explanation of this relationship but I did not: https://docs-bigbang.dso.mil/2.2.0/docs/understanding-bigbang/package-architecture/authservice/ - Wording changes for precision. Example, in MetricsServer, speaking of "container" metrics is more precise (and I believe more accurate) than "cluster" metrics. If it reports on nodes and containers I would (personally) speak of both over the more nebulous "cluster" (which has many more primitives (notably servics and pods) which could be but are not (I think) being reported on). - Most likely errors needing correction: - Metrics Server may be misunderstood - AuthService may be better characterized but I didn't want to plagarize the BigBang docs, and am new to this service. ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [X] Other (security config, docs update, etc) ## Checklist before merging - [x] Test, docs, adr added or updated as needed - [x] [Contributor Guide Steps](https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md)(https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md#submitting-a-pull-request) followed --------- Co-authored-by: Micah Nagel <micah.nagel@defenseunicorns.com>
rjferguson21
pushed a commit
that referenced
this pull request
Jul 11, 2024
🤖 I have created a release *beep* *boop* --- ## [0.23.0](v0.22.2...v0.23.0) (2024-07-04) ### ⚠ BREAKING CHANGES * remove emulated gitlab endpoints from keycloak ([#483](#483)) ### Features * identity group auth ([#497](#497)) ([d71d83e](d71d83e)) ### Bug Fixes * **docs:** re-ordered small paragraphs, clarified wording, and added links to tech homepages ([#531](#531)) ([6b2b46b](6b2b46b)) * **docs:** removed double-link which broke the markdown formatting in pr template ([#532](#532)) ([f41ced4](f41ced4)) * **docs:** uds-config.yaml example in k3d-slim-dev README ([#530](#530)) ([2e1c53e](2e1c53e)) * operator retries and error logging ([#511](#511)) ([cae5aab](cae5aab)) ### Miscellaneous * **deps:** update checkout action to latest sha ([#481](#481)) ([c6f0137](c6f0137)) * **deps:** update dependency weaveworks/eksctl to v0.183.0 ([#499](#499)) ([9cb8e4d](9cb8e4d)) * **deps:** update grafana to 11.1.0 ([#380](#380)) ([499058a](499058a)) * **deps:** update istio to v1.22.2 ([#512](#512)) ([dcdadb4](dcdadb4)) * **deps:** update jest to v29.1.5 ([#485](#485)) ([9c392b9](9c392b9)) * **deps:** update neuvector to 5.3.3 ([#467](#467)) ([261057d](261057d)) * **deps:** update pepr to 0.32.2 ([#473](#473)) ([ab4bee9](ab4bee9)) * **deps:** update pepr to 0.32.3 ([#494](#494)) ([2e28897](2e28897)) * **deps:** update pepr to 0.32.6 ([#516](#516)) ([a9d3eec](a9d3eec)) * **deps:** update promtail to 3.1.0 ([#335](#335)) ([4457fce](4457fce)) * **deps:** update uds to v0.12.0 ([#521](#521)) ([8e587ff](8e587ff)) * **deps:** update uds-common tasks to 0.6.1 ([#498](#498)) ([4aa6e33](4aa6e33)) * **deps:** update zarf to v0.35.0 ([#490](#490)) ([86957cf](86957cf)) * docs linting changes ([#505](#505)) ([0fe2015](0fe2015)) * remove emulated gitlab endpoints from keycloak ([#483](#483)) ([495960c](495960c)) * update docs for group auth and readme for docs site ([#540](#540)) ([ace7041](ace7041)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
As a new Unicorn, I made changes which I believe would've increased my comprehension of this document on the first read-through.
Description
Type of change
Checklist before merging