About the Foundation for Public Code

Write a guide

This guide


  1. Where your guide lives
  2. Anatomy of a guide
    1. Metadata
    2. Title
    3. Content
    4. Further reading section
    5. Example guides
  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 <//about.publiccode.net>. It should be in a relevant place in the folder structure. Often this is with an activity.

Anatomy of a guide


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.


The front matter is followed by the title of your guide

# Making awesome dog and pony videos


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)

Example guides

Further reading