-
Notifications
You must be signed in to change notification settings - Fork 18
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add "Types of Documentation" article #656
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||
---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,69 @@ | ||||||||
--- | ||||||||
title: Types of Documentation | ||||||||
description: An overview of the different types of documentation resources and where to find them | ||||||||
layout: article | ||||||||
category: Handbook | ||||||||
--- | ||||||||
|
||||||||
While this handbook covers topics relevant for all of the Login.gov team, it's not the only place | ||||||||
that you can expect to find documentation resources. | ||||||||
|
||||||||
This article outlines the different locations for documentation, and what content you should expect | ||||||||
to find in each. | ||||||||
|
||||||||
## [Login.gov Public Handbook](https://handbook.login.gov/) | ||||||||
|
||||||||
- Contains content relevant for the entire Login.gov program which is suitable to share with the | ||||||||
general public (see [_Sensitive Information_](https://handbook.login.gov/articles/contributing.html#sensitive-information)) | ||||||||
- Anyone can and should contribute, but content is written in [Markdown](https://en.wikipedia.org/wiki/Markdown) | ||||||||
and therefore requires some understanding of Markdown syntax | ||||||||
- 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 | ||||||||
|
||||||||
## [Login.gov Internal Handbook](https://lg-public.pages.production.gitlab.login.gov/identity-internal-handbook/) | ||||||||
|
||||||||
- Contains content relevant for the entire Login.gov program which is not suitable to share with the | ||||||||
general public (see [_Sensitive Information_](https://handbook.login.gov/articles/contributing.html#sensitive-information)) | ||||||||
- Anyone can and should contribute, but content is written in [Markdown](https://en.wikipedia.org/wiki/Markdown) | ||||||||
and therefore requires some understanding of Markdown syntax | ||||||||
- 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 | ||||||||
|
||||||||
## [Login.gov Google Drive](https://drive.google.com/drive/folders/0AJJ3eelM4E-NUk9PVA) | ||||||||
|
||||||||
- Contains both program-wide and team-specific content, organized into team or topic folders | ||||||||
- Content is generally less structured, and many documents are not expected to be kept up-to-date | ||||||||
- Google Docs offers an easy-to-use experience for writing content, and changes can be made without | ||||||||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
## Login.gov Project Repositories | ||||||||
|
||||||||
- Contains project-specific content | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
- Content is written in [Markdown](https://en.wikipedia.org/wiki/Markdown) | ||||||||
- Content is readable through local copies of the project or in the GitHub/GitLab web interface, but | ||||||||
is not otherwise available at a website | ||||||||
- 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 discoverable through GitHub/GitLab search, which often produces low-quality results | ||||||||
|
||||||||
Examples: | ||||||||
|
||||||||
- [`18f/identity-idp` docs](https://github.com/18F/identity-idp/tree/main/docs) | ||||||||
- [`18f/identity-site` docs](https://github.com/GSA-TTS/identity-site/tree/main/docs) | ||||||||
|
||||||||
## GitLab Wikis | ||||||||
|
||||||||
- Contains team-specific or project-specific content | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||||||||
- Content changes can be made without an approvals process | ||||||||
- 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
Examples: | ||||||||
|
||||||||
- [DevOps Wiki](https://gitlab.login.gov/lg/identity-devops/-/wikis/home) | ||||||||
- [Team Katherine Wiki](https://gitlab.login.gov/groups/lg-teams/katherine/-/wikis/home) |
Original file line number | Diff line number | Diff line change | ||||||
---|---|---|---|---|---|---|---|---|
|
@@ -64,7 +64,8 @@ span { | |||||||
* Mimics private-eye lock emoji, but for GitLab repos | ||||||||
* See https://github.com/18F/private-eye/blob/c08740d838eb2b95b318a916894c6cb6aae76e41/private-eye.js#L5 | ||||||||
*/ | ||||||||
a[href*="gitlab.login.gov/lg"] { | ||||||||
a[href*="gitlab.login.gov/lg"], | ||||||||
a[href*="gitlab.login.gov/groups/lg"] { | ||||||||
Comment on lines
+67
to
+68
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. should we just do anything at that domain?
Suggested change
|
||||||||
& > strong::after, | ||||||||
&::after { | ||||||||
content: "\1F98A"; // 🦊 | ||||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.