Skip to content
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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions _articles/types-of-documentation.md
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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Can have pages that redirect to to [Login.gov Google Drive](#logingov-google-drive) to make them easier to find

## [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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Sometimes copied from specific templates, see [Product Artifacts]({% link _articles/product-artifacts.html %})

## Login.gov Project Repositories

- Contains project-specific content
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Contains project-specific content
- Usually public information, since most repositories are public
- Contains project-specific content

- 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Limited to users with GitLab accounts (not accessible to entire Login.gov team)

- 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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Changing the title of a page can break links to the page

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)
3 changes: 2 additions & 1 deletion assets/scss/main.css.scss
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"] {

& > strong::after,
&::after {
content: "\1F98A"; // 🦊
Expand Down
Loading