Project documentation

It should contain every aspect that the developer needs to know and that cannot be received directly from the code. These include development dos and don’ts, full deployment instructions, external integration descriptions, and so on. This post will guide you through creating a powerful, beautiful and legible README file for your project.

A nice introduction for well-prepared project documentation can be found on github guides: https://guides.github.com/features/wikis/. This states that “README should contain only the necessary information for developers to get started using and contributing to the project”.

With this in mind, let’s introduce a list of components and best practices we follow at Codest for creating project documentation.

Quick introduction

– Project title: this is a must-have for every README.

– Status badges: if you use any external code quality measurements, automated testing or other tools, the beginning of the document is a good place to show others if they work.

– Description: include a few sentences about the project to quickly describe the main purpose and what it does.

Table of contents

A contents list can be useful for long documentation files, but if your README is quite concise then it is not necessary.

General information

– About section: this should be a more detailed description of the project – it may include information about users, their roles, some more-confusing cases, and screenshots, etc.

– Mockups: a place for links to UI/UX mockup resources if there are any.

• Other information like Access to servers or Integration with external APIs: examples include a staging instance url address, shared non-sensitive (!) access credentials, links to documentation, some instructions, etc.

Installation

– Requirements: prerequisites that must be fulfilled before starting an application setup, e.g. external tools installation.

– Setup: a step-by-step instruction to follow to get the project up and running.

– Settings: describe where local settings are stored and provide instructions on how to receive your own settings.

– Local configuration: if there are some cases for local setup, this is a good place for an explanation.

Development

This section is an ideal place for instructions such as feature development, bugfixes, hotfixes, common features, testing, style guides, code organisation, other development tools used in the project (e.g., guards or dockers), and so on. Don’t forget to mention all the rules that every team member should know.

Deployment

Provide clear step-by-step instructions for each environment and everything that is “good to know” while making the deployment.

Other ideas for separate sections

– API documentation

– Changelog

– External resources: a place for all sort of links that may be helpful.

– Application stack: a list of the application stack that we use in the project – may contain a short description and the name of the provider.

Team

It’s debatable whether it’s necessary to show current project team members (github provides the full list of contributors by default) but it’s always nice if you see your name as one of the authors of a project. If you do this, keep it as up-to-date as possible.

A final few words

Remember: each project is unique and so is its documentation. There is no one great solution for writing a README. Just follow the general tips, and the most important thing is to always remember about refactoring, which also connects to the README. It is always a good idea to look at the document as a whole and rethink it if something needs to be displayed in a different way.

One more thing: “instructions” are key so write them a lot. Thank you!

Read more:

• Open-closed principle. Do I ever have to use it?
• How to write a good and quality code?
• Vuelendar. A new Codest’s project based on Vue.js