Add "Types of Documentation" article #656
Open
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
zachmargolis
approved these changes
Jan 17, 2025
| - Content is changed through pull requests in [the GitHub repository](https://github.com/GSA-TTS/identity-handbook), | ||
| which requires some understanding of Git, and requires an approving peer review | ||
| - Content is intended to be highly discoverable using website search functionality | ||
|
|
There was a problem hiding this comment.
Suggested change
| - Can have pages that redirect to to [Login.gov Google Drive](#logingov-google-drive) to make them easier to find | |
| - Wikis offer basic top-down (parent-child) structuring, without much flexibility for further | ||
| customization (e.g. ordering) | ||
| - Content is discoverable through GitHub/GitLab search, which often produces low-quality results | ||
|
|
There was a problem hiding this comment.
Suggested change
| - Changing the title of a page can break links to the page | |
|
|
||
| ## GitLab Wikis | ||
|
|
||
| - Contains team-specific or project-specific content |
There was a problem hiding this comment.
- Limited to users with GitLab accounts (not accessible to entire Login.gov team)
|
|
||
| ## Login.gov Project Repositories | ||
|
|
||
| - Contains project-specific content |
There was a problem hiding this comment.
Suggested change
| - Contains project-specific content | |
| - Usually public information, since most repositories are public | |
| - Contains project-specific content |
| an approvals process | ||
| - Content is discoverable through Google search, but it can be difficult to find timely and | ||
| program-specific documents without extensive use of filters | ||
|
|
There was a problem hiding this comment.
Suggested change
| - Sometimes copied from specific templates, see [Product Artifacts]({% link _articles/product-artifacts.html %}) | |
Comment on lines
+67
to
+68
| a[href*="gitlab.login.gov/lg"], | ||
| a[href*="gitlab.login.gov/groups/lg"] { |
There was a problem hiding this comment.
should we just do anything at that domain?
Suggested change
| a[href*="gitlab.login.gov/lg"], | |
| a[href*="gitlab.login.gov/groups/lg"] { | |
| a[href*="gitlab.login.gov"] { |
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 of changes
Adds a new article "Types of Documentation"
At our recent Handbook Documentation Club meeting, we discussed the "what and where" of our different types of documentation. This article exists to capture this in a way that can be shared with others to help explain where they can expect to find (or author) some type of documentation.
Usually, this comes down to:
And to a lesser extent:
📜 Testing Plan
Review the new article content for accuracy and readability.
Preview URL: https://federalist-7d0b2b76-42fc-4df1-9825-8c3cd77e0a15.sites.pages.cloud.gov/preview/gsa-tts/identity-handbook/aduth-types-of-documentations/articles/types-of-documentation.html