Basics of Documentation

We need documentation for knowledge transfer, to maintain a single source of truth, and keep a record of existing features or workflow to avoid duplication of efforts. It is a way through which creators can connect and convey their ideas with contributors for effective collaboration. While developing something, you will reach a point in the future where you need references to your feature implementations, that’s where well-written documentation comes in handy.

For instance, you work with a small organization with a minimal team size. You may have the bandwidth to host frequent knowledge transfer sessions to explain your codebase to a newly joined employee or every time someone transitions from another project without writing robust documentation. But the same cannot be feasible for an upscaled firm with a large team footprint or a product that has grown leaps and bounds in complexity and size.

Or, if you encounter a complex problem, you spend your time working around it only to find out later that someone else has already solved it using a similar implementation. This could’ve been avoided if that approach was well documented and revisited.

Good documentation should answer three questions clearly — What, Why, and How.

The ‘what’ part explains what the project is about, and what problem statement it aims to solve. Taking a look at open source projects across the web, you would find this to be the starting point of their documentation. It is usually included in a README file. This is also the piece of information an end user or a first-time contributor will come across when scouting through the project files.

The ‘why’ part should be concise. It should explain why your project should be contributed to or used by an end user. You may include the differentiating factor that sets your product apart from its competitors.

The ‘how’ part should explain two shows — how to install and how to use. People must be able to install your project in order to contribute or use it. Without this knowhow, you will hit roadblocks in expanding the scope of your project. The ‘how to use’ section can briefly explain any prerequisites or setup configurations that must be done after the first installation.

Every documentation has an audience — developers and end users. The content of which must be highly tailored according to the readers aka less technical jargon for sections meant for end users.

• Some good practices to follow while writing robust documentation.
• Include code snippets, sample videos or tutorials where possible, especially if documenting UI.
• Maintain standard coding conventions with consistent and descriptive naming schemes.
• Add a contributing guide to expedite the onboarding of new contributors.
• Include license information with the documentation.
• Maintain and update a changelog of different builds of your products-experimental, production, etc.

Atharva Naik