Guide: How to Format Guide
This guide documents how to write documentation about tools, Processes and Practices (P&Ps) used or created at Hack for LA. Our guides are used to document and standardize Tools and P&Ps. Use this guide to create your guide so that future users will have a clear reference and examples on how to replicate your success.
For this guide, the audience is documenting processes and tools; if you are looking for a guide to documenting projects for external stakeholders, the Guide: How to Write a One Sheet may be more useful.
Write the guide to document how the user should achieve the desired goal.
- Guides should be clear overviews of the process.
- Write with a clear idea of the user’s problem and goal in mind.
- Aim to give users enough information to be able to move forward.
- If there is detail that a user might need but is a fringe case, add an Additional Reference Material or Glossary section at the end to include the information.
- Make a separate guide for any sub practices or processes and link to it from the relevant location in your guide if the guide is too long and/or parts of the guide would be useful by themselves.
Process documentation should provide overviews of the process, detail how to implement the process and how to handle typical deviations.
Example:
Overview of the process a new issue takes to be useful to the team (outdated, since it's missing the New Issue Approval column)
Document the steps needed to accomplish a specific task. The steps should be clear and brief, since the user’s goal will be to read them (often only once), do the task described, and continue with their work.
It may be helpful to approach this as a use case. Include visuals when possible, to make it easier for the user to understand the documentation.
- Create a place to store the documentation you will be creating on the Engineering Wiki
- Navigate to the guides' page for your community of practice
- Create a new page for the guide, calling it the name specified in your GitHub issue (usually something such as Guide: How to ZYZ)
- Add a link to the page to the issue you are working from
- Make a header by using this template and save it into the page you have created
- Use this template to start your guide
- Name the guide the same as the page you have created