Skip to content

Add a Guide article

Jump to bottom
Jeff Fredrickson edited this page Nov 30, 2017 · 3 revisions

The Tech Guides section of the website serves as a knowledge base. You can write articles for the Tech Guides simply by adding a new Markdown file to the _guides directory. For instance, say you want to write an article on "API Standards". Copy the file _guides/_TEMPLATE.md to a new file, _guides/api-standards.md, then follow the instructions in the file.

The template file includes some helpful information on how to get started. Also, see the Style Guide to learn how to keep all guide pages consistent in appeareance.

Adding a Guide

  1. Create a feature branch based on the master branch. Prefix it with your initials, followed by _, and then a brief summary of the changes you're going to make, e.g., sc_new-agile-guide (see branching tutorial).
  2. Make the following changes in your feature branch, not on master:
    1. Go to the _guides folder.
    2. Click the Create new file button.
    3. Name the file something relevant to the guide, such as agile-guide.md. It should be lowercase, use hyphens instead of spaces, and end with the extension .md.
    4. Optionally, you can get started by pasting in the contents of _TEMPLATE.md.
    5. When you are done, commit the file with a descriptive message.
  3. Preview your changes at https://federalist.18f.gov/preview/gsa/cto-website/BRANCH_NAME/ (where BRANCH_NAME is the name of your feature branch, e.g., sc_new-agile-guide)
  4. Open a pull request to merge the feature branch to master (see pull request tutorial).

Updating a Guide

  1. Create a feature branch based on the master branch. Prefix it with your initials, followed by _, and then a brief summary of the changes you're going to make (e.g., sc_update-agile-guide). View this tutorial for help in creating branches on GitHub.
  2. Make the following changes in your feature branch, not on master:
    1. Go to the _guides folder.
    2. Edit the Guide file.
    3. When you are done, commit the file with a descriptive message.
  3. Preview your changes at https://federalist.18f.gov/preview/gsa/cto-website/BRANCH_NAME/
  4. Open a pull request to merge the feature branch to master (see pull request tutorial).
Clone this wiki locally