Types of Documentation

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

  • Contains up-to-date content relevant for the entire Login.gov program which is suitable to share with the general public (see Sensitive Information)
  • Anyone can and should contribute, but content is written in Markdown and therefore requires some understanding of Markdown syntax
  • Content is changed through pull requests in the GitHub repository, which requires some understanding of Git, and requires an approving peer review
  • Content is intended to be highly discoverable using website search functionality
  • Can have pages that redirect to to Login.gov Google Drive to make them easier to find

Login.gov Internal Handbook

  • Contains up-to-date content relevant for the entire Login.gov program which is not suitable to share with the general public (see Sensitive Information)
  • Anyone can and should contribute, but content is written in Markdown and therefore requires some understanding of Markdown syntax
  • Content is changed through pull requests in the GitHub repository, 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

  • 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
  • Sometimes copied from specific templates (see Product Artifacts)

Login.gov Project Repositories

  • Usually public information, since most repositories are public
  • Contains project-specific content
  • Content is written in 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, 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:

GitLab Wikis

  • Contains team-specific or project-specific content
  • Requires a GitLab account to access
  • 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
  • Changing the title of a page can break links to the page

Examples: