About the Foundation for Public Code

Write a guide

This guide

Contents

  1. Where your guide lives
  2. Anatomy of a guide
    1. Metadata
    2. Title
    3. Content
    4. Further reading section
  3. Further reading

Guides are how we explain things to each other. The goal of a guide is always to help others go through a process and get to a result, preferably by themselves.

Capturing knowledge about our processes as guides helps onboard newcomers and gives insight into how we work.

A guide is always written to help the reader (you) progress.

Where your guide lives

Guides are published on . It should be in a relevant place in the [folder structure](/activities/documentation/about-folder-structure.html). Often this is with an activity.

Anatomy of a guide

Metadata

The MarkDown of a guide file starts with the following metadata front-matter:

---
type: Guide
explains: How to make pancakes for hungry people
---

After the explains you should set out what this guide tries to explain and to whom - this is the goal of the guide. Writing this first will help you scope what you are explaining and will provide a clear answer for readers on whether this is for them.

Title

The front matter is followed by the title of your guide


# Making awesome dog and pony videos

Content

Followed by the content of the guide.

Further reading section

At the end of your guide you can add a ‘Further reading’ section with relevant links to anything inside or outside of About that people can use in order to understand this topic better.

## Further reading

* [Find great cat gifs on Giphy](https://giphy.com)
* [Find great dog videos on YouTube](https://youtube.com)

Further reading