As a software engineer, I have worked on multiple projects with various setups and architectures. One of the most challenging tasks I face initially is setting up the environment and understanding the code flow.
In simple projects with a straightforward codebase, everything goes smoothly. However, in large-scale systems that involve multiple services and complex architectures, good documentation becomes essential.
Here are some tips for writing good documentation:
Keep it simple: A document should focus on one topic, providing clear and concise instructions. It should offer a straightforward list of actions, giving users an overview of the project.
Write for a specific audience: Tailor the documentation to the intended audience. Writing for your team requires a different approach than writing for your manager.
Clearly explain big concepts: Strive for clarity when explaining large concepts. My own documentation can sometimes be verbose, so I aim to keep it concise while maintaining clarity. Include flow charts, comparison tables, and diagrams to enhance readability.
Take the task seriously: Writing good documentation can enhance your skills. Being a software engineer involves more than just writing code—it also requires effective communication and producing good documentation is part of that.
Let's take an example for demonstration. The topic will be how to write a README file for a ReactJS project. Here are my steps:
Define the audience: This README file is for developers who are new to the project and want to understand the overview of the project.
Define the key points for the README file, including:
a. Overview of the project: its purpose and business perspective.
b. Instructions on how to install the project locally.
c. Instructions on how to run the project locally.
d. Description of the project's current features.
e. Details about the project's tech stack.
f. How to debug the project.
g. Additional details such as design links, accounts, Jira links, code flow, etc.
Review the file content multiple times to find errors, fix them, and rewrite as necessary.
Request feedback from early readers or coders to review the README.
Update the document as needed when certain topics are unclear.
The main goal when writing a README file is to ensure that anyone new to the project can understand the basics of the project without needing to ask others for assistance.
In conclusion, not everyone may have a natural talent for writing good documentation. However, with practice and guidance, you can improve your documentation skills just as I have done over time.