README.md — what’s in yours?
README files are a massively important part of a project, typically containing critical information about the build and development a project.
Having a consistent approach to README files across a development team can prove to be very useful. Here’s a template / guide that you can use.
Project Overview
This should be a brief description as to the why the project was undertaken, and a brief description as to what the project is. For consistency across the project, and to avoid recreating the wheel, it might be worth checking with the account handlers on the project to see if they have a few paragraphs of text that have already been produced that cover this.
Installation of Development Environment
Does your project use a development environment that is different to that specified in the Developer Continuity document? If so provide information as to how other developers can recreate the environment on their machines. Even if it’s as simple as npm install, make sure that this is clearly documented, and that all dependencies are included in the package.json and are available remotely.
Related Docs
Although you should be keeping your documentation as concise as possible, sometimes it will be necessary to separate documentation in different files. If this is the case include a linked list of all related documents here. These should be located within the docs folder of your project.
- docs/build-tasks
- docs/server-configuration
- docs/debugging
Related Repositories / Project Components
Does the project you’re working on have a number of components that are in different branches or repositories? If so link to them here, and where necessary give a little explanation as to what the component is, for example: WebApp, Backend, iPhone App.
- git/client/project-x-webapp — WebApp
- git/client/project-x-backend — Backend
- git/client/project-x-iphone — iOS Application
Directory Structure
How have you structured your project? Where can I find the files that I need? What is your reasoning behind this structure?
Code / Dependencies
Is there a specific coding style or design pattern that you’ve been working to? What dependencies does the project have? Are you using third party libraries? Does the project require any specific environment configurations or hardware configurations?
Build Commands
If your project uses build commands make sure that they are included here. Give explanation as to what the commands do, give an example of their usage and specify and parameters / variables that can be used with them.
Future Vision / Making Changes
If someone else were to pick up this project, how would you want them to make changes? Has your code been produced in an extensible way, where by you’ve factored in an existing method or framework for adding / removing / toggling functionality.
