Show Menu
Cheatography
  1. Home >
  2. Programming >

QK Standard README.md Cheat Sheet (DRAFT) by

The official QK README.md cheat sheet.

This is a draft cheat sheet. It is a work in progress and is not finished yet.

Sections

Title
Required
Usually this should be the repository name
Table of Content
Optional
Strongly recomm­ended if you have a long README
Summary
Required
Summary of the content of the repository
Features
Optional
Feature of your tool, modules, library
Prereq­uisites
Required
Prereq­uisites for using your tool, module, library
Usage
Required
Basic usage for your tool, module, library
Examples
Optional
More specific examples of how to use your tool, module, library
Common Problems
Optional
If any identi­fied, list the common problems that users can encounter here
terraf­orm­-docs Sections
Required (TF Module)
For Terraform modules, ensure you run the 
terraf­orm­-docs
tool to include generated docume­ntation for your module
This is a list of "­sta­nda­rd" sections but you do not have to limit yourself to these sections. Feel free to add any other sections that would improve docume­nta­tion, user experi­ence, and minimize end-user questions and support requests.

Recomm­ended Tools

QK's preferred code editor
Helps ensure consistent Markdown structure and format
Helps ensure your README does not have any typo
Helps creating Markdown table of content
Helps creating Markdown tables
 

Title

To keep things simple, you should usually set the title to the name of the repository since the README.md file is displayed by BitBucket.

Table of Content

If you have a somewhat long README, we strongly recommend you add a ToC section so that users can have a quick view of all the content in your README and easily jump to a section they wish to read. We recommend you use a VS Code extension for this as creating the ToC manually is tedious.

Summary

Summary of the content of the reposi­tory. This is usually a one-liner or a short paragraph. If desired, you can put this directly under the "­Tit­le" section. The goal is to let the user know early what the repository contains.

Features

When creating a generic tool, module or library, we strongly recommend you create a "­Fea­tur­es" section to "­sel­l" it to potential users. The main benefit of such tools, modules or libraries is to standa­rdize how things are done and provide users with easy to consume "­LEG­O" blocks on which they can build more complex projects. If you invested time to make your tool "­usa­ble­" by many, you should take the time to explain its features and "­sel­l" it to potential users so it bring value to many, not only you.

Prereq­uisites

Ensure you document any prereq­uisites (software, steps, permis­sions, etc) needed to use the content of your reposi­tory. Doing so will ensure people who takes the time to read your docume­ntation will not waste any time trying to make things work when they unknow­ingly are missing prereq­uis­ites. It will also minimize questions and complaints from users.

Usage

Make sure you provide users with basic usage inform­ation for the content of your reposi­tory. What may seem evident to you may not be clear to others without context and explan­ations. This section should include the minimal inform­ation to get users up-and­-ru­nning.
 

Examples

In this section, you should include examples of how to use the content of your reposi­tory. It can be task-f­ocused (e.g. To do this: Use this way), it can include code to show some common usage patterns or it can refer to more complete examples stored in the reposi­tory. You are free to use the format you want, the goal is to provide the users with common examples they can learn from.

Common Problems

When you are aware (e.g. from your own experience or from user feedback) of common questions, problems, pitfalls or limita­tions, you should document them in this section. When you have solution or workar­ounds you should include them as well. The goal is to empower the user with the inform­ation needed to fix "­mos­t" issues already identified and minimize questions and compla­ints. --- As your repository become more popular, you may identify new questions or issues. When you do, you should update your README with new content.

terraf­orm­-docs Sections

Required for all Terraform Modules. Please see the Terraform module specific cheat sheet for details.

Tips

Always include a 
README.md
file in all your reposi­tories. This file is automa­tically displayed by BitBucket and act as the main docume­ntation for your reposi­tory.
If your repository is published (public or to other project members), make sure your 
README.md
file includes the 
Required
sections.
When necessary, feel free to add per-di­rectory 
README.md
files inside your project to further improve docume­nta­tion. These READMEs don't have to include all sections, they can simply include inform­ation more specific to this part of the reposi­tory.
As the content of your repository changes, do not forget to update your README file(s).