In the previous post I shared tips for writing a better README. Today I'd like to share my README template with you.
This template is probably much more involved that other README files that you have seen. This template is meant for developers who are committed to a standard of excellence and want to provide quality documentation for their projects. Our goal is to anticipate users' questions before they encounter them and make our documentation as comprehensive as possible. By putting effort into your documentation, you make it much easier for other developers to use and contribute to your projects.
README Template (Markdown)
# Project Title Provide an introductory paragraph, describing: * What your project does * Why people should consider using your project * Link to project home page ## Table of Contents 1. [About the Project](#about-the-project) 1. [Project Status](#project-status) 1. [Getting Started](#getting-started) 1. [Dependencies](#dependencies) 1. [Building](#building) 1. [Installation](#installation) 1. [Usage](#usage) 1. [Release Process](#release-process) 1. [Versioning](#versioning) 1. [Payload](#payload) 1. [How to Get Help](#how-to-get-help) 1. [Further Reading](#further-reading) 1. [Contributing](#contributing) 1. [License](#license) 1. [Authors](#authors) 1. [Acknowledgements](#acknowledgements) # About the Project Here you can provide more details about the project * What features does your project provide? * Short motivation for the project? (Don't be too long winded) * Links to the project site ``` Show some example code to describe what your project does Show some of your APIs ``` **[Back to top](#table-of-contents)** # Project Status Show the build status if you have a CI server: [![Build Status](http://your-server:12345/job/badge/icon)](http://your-server:12345/job/http://your-server:12345/job/badge/icon/) Describe the current release and any notes about the current state of the project. Examples: currently compiles on your host machine, but is not cross-compiling for ARM, APIs are not set, feature not implemented, etc. **[Back to top](#table-of-contents)** # Getting Started This section should provide instructions for other developers to These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system. ## Dependencies Describe what software and libraries you will need to install in order to build and use this project. Provide details on how to resolve these dependencies. Remember: git-lfs is a dependency that developers will need to resolve before they can get started with a repo using LFS. ``` Examples should be included ``` ## Getting the Source Include a link to your github reposistory (you have no idea how people will findy our code), and also a summary of how to clone. This project is [hosted on GitHub](https://github.com/embeddedartistry/embedded-resources). You can clone this project directly using this command: ``` git clone firstname.lastname@example.org:embeddedartistry/embedded-resources.git ``` ## Building Instructions for how to build your project ``` Examples should be included ``` ## Running Tests Describe how to run unit tests for your project. ``` Examples should be included ``` ### Other Tests If you have formatting checks, coding style checks, or static analysis tests that must pass before changes will be considered, add a section for those and provide instructions ## Installation Instructions for how to install your project's build artifacts ``` Examples should be included ``` ## Usage Instructions for using your project. Ways to run the program, how to include it in another project, etc. ``` Examples should be included ``` If your project provides an API, either provide details for usage in this document or link to the appropriate API reference documents **[Back to top](#table-of-contents)** # Release Process Talk about the release process. How are releases made? What cadence? How to get new releases? ## Versioning This project uses [Semantic Versioning](http://semver.org/). For a list of available versions, see the [repository tag list](https://github.com/your/project/tags). ## Payload **[Back to top](#table-of-contents)** # How to Get Help Provide any instructions or contact information for users who need to get further help with your project. # Contributing Provide details about how people can contribute to your project. If you have a contributing guide, mention it here. e.g.: We encourage public contributions! Please review [CONTRIBUTING.md](docs/CONTRIBUTING.md) for details on our code of conduct and development process. **[Back to top](#table-of-contents)** # Further Reading Provide links to other relevant documentation here **[Back to top](#table-of-contents)** # License Copyright (c) 2017 Embedded Artistry LLC This project is licensed under the MIT License - see [LICENSE.md](LICENSE.md) file for details. **[Back to top](#table-of-contents)** # Authors * **[Phillip Johnston](https://github.com/phillipjohnston)** - *Initial work* - [Embedded Artistry](https://github.com/embeddedartistry) See also the list of [contributors](https://github.com/your/project/contributors) who participated in this project. **[Back to top](#table-of-contents)** # Acknowledgments Provide proper credits, shoutouts, and honorable mentions here. Also provide links to relevant repositories, blog posts, or contributors worth mentioning. Give proper credits. This could be a link to any repo which inspired you to build this project, any blogposts or links to people who contributed in this project. If you used external code, link to the original source. **[Back to top](#table-of-contents)**