As a developer, you will spend a lot of time reading through documentation and writing technical documentation for other developers. For instance, you may need to write a README for a project, or make updates to internal and external docs. The next time you find yourself writing documentation, consider these three tips to make your writing more approachable, understandable, and enjoyable.
1. Write Documentation From the Perspective of Someone New to the Project
When writing documentation for a project, it helps to write in a way that teaches someone with very little knowledge how to get up and running. A lot of documentation assumes prior knowledge of the codebase, tools, and APIs. Developers of all levels of expertise will be reading this documentation to help themselves get started and eventually become expert code contributors.
Your documentation will be the most helpful to new developers if it includes links to topics that require prior knowledge. You don’t have to explain every little detail, but you should guide them to more resources. For example, React’s documentation does a good job of linking to a refresher on JavaScript and various JavaScript statements.
2. Update As the Project Evolves
Often times, the documentation that you write at the beginning of the project will need to change by the end of the project. Anytime you add, remove, or change a feature, document it. If this is hard to remember, set yourself a reminder once a month to revisit the documentation. Keeping the documentation up-to-date will be beneficial to future developers coming onto the project.
3. Ask Others to Review Your Current Documentation
Having other developers with various levels of experience review your documentation will help you see areas for improvement. Take any questions a developer may have about your documentation and use those answers to update your documentation. If a person unfamiliar with the project is able to get it up and running with few questions, then you know you’ve done a solid job of documenting. If you’re pressed for time, having many developers review your documentation may not be feasible, but it’s nice to have one other set of eyes look it over.
Better Documentation Makes Everyone’s Job Easier
Combing through poor documentation can be stressful and a time waste when trying to find answers. Great documentation will make developers more efficient. If they don’t need as many questions answered, they can focus more on the problem and producing great work, which benefits everyone.
