How much documentation should I write to avoid team complaints?

Dude, this question is a classic, practically every engineer's "soul-searching" dilemma. In the office, arguments over documentation are just as common, if not more so, than arguments over code style.

Honestly, there's no standard answer like "write XX pages" or "XX words" for this. If someone tells you "every function needs a comment," just block them, especially in a startup; doing that would kill the project.

The key isn't "how much," but "who is it for" and "under what circumstances." Imagine documentation as you talking to someone in the future. This person could be:

• Yourself three months from now: ("What on earth was I thinking when I wrote this piece of code?")
• A newly onboarded colleague: ("Hey senior, how do I get this project running? I want to debug it locally.")
• Another poor soul woken up in the middle of the night to fix a bug: ("What does this API do? Why is the data it returns so weird?")
• A colleague from another team who needs to use your module: ("How do I use your tool? Can you give me an example to copy?")

Once you're clear about who you're talking to, you'll know what to write and how much.

Here are a few scenario-based suggestions you can follow to ensure no one on your team bothers you about documentation:

1. "Lifesaving" Documentation: A Must-Have, or Everyone's Doomed

This type of documentation has the highest priority. It's not extensive, but its absence can lead to major problems.

• How to Run the Project: A README.md file that clearly states:
  1. What the project does (a one-sentence explanation).
  2. How to install dependencies (npm install, pip install -r requirements.txt, etc.).
  3. How to start the service (npm run dev, python manage.py runserver).
  4. How to run tests.
  • Purpose: To enable new colleagues to get the project running on their own machine within half an hour, instead of asking you questions all day. This is a "lifeline" for newcomers and peace of mind for yourself.
• Environment Configuration Instructions: For example, a .env.example file listing all necessary configuration variables, with comments explaining what each variable does. Never put passwords or secret keys directly in it!
  • Purpose: To prevent others from spending a whole morning on environment issues, only to find out a certain configuration was missing.
• Deployment and Release Process: If the project requires manual deployment, be sure to document the steps. Even if it's just in a note-taking app visible only to your team.
  • Purpose: To prevent a situation where only you know how to deploy, and if you're on vacation, the project can't go live.

2. "Signpost" Documentation: Written in Code, Guiding Those Who Read It

This type of documentation isn't a lengthy treatise, but rather "highlighted comments" within the code.

• Explain "why" it's done this way, not "what" it does:
  • Bad example: // Loop through user list (Isn't that obvious?)
  • Good example: // We're not using a regular forEach here because we need to accommodate a peculiar IE8 bug.
  • Good example: // WARNING: The performance of the function below is extremely poor; it's a temporary solution and needs to be refactored into the xxx pattern later.
• Complex Business Logic: If a piece of code has convoluted business logic, such as a function for calculating points or coupons, it's best to explain the rules in a few sentences at the beginning of the function.
  • Example: // Final price calculation rules: 1. Prioritize the coupon with the highest discount; 2. Points and coupons cannot be used simultaneously; 3. VIP users get an additional 5% discount on top of that.
• API Interface Comments: If you're writing backend APIs, briefly explain what the interface does, what parameters it requires, and what it returns, right above the interface definition.
  • Purpose: To allow frontend or client-side colleagues to understand how to call the API without having to dig through your code. Many frameworks can now automatically generate API documentation (like Swagger), saving a lot of effort.

3. "Instruction Manual" Documentation: For Those Who Use Your Stuff

If you've created a public component, a utility library, or a service for others to use.

• Provide an out-of-the-box example: Don't write lengthy explanations about your design philosophy. Instead, provide the simplest, runnable code snippet that others can copy and paste to use immediately.
• Key Parameter Explanations: List the most important parameters, explain what they do, and what their possible values are.

In Summary

Don't treat writing documentation as an extra, annoying task. See it as part of the code, a way to communicate with the future.

Your goal isn't to write an encyclopedia, but to:

• Enable new colleagues to be self-sufficient.
• Allow collaborators to self-diagnose.
• Prevent your future self from cursing.

Achieve these three points, and you'll be the coolest person on the team; no one will ever diss you over documentation. Remember, the best documentation is "just right" documentation—it neither lacks critical information nor contains any superfluous words.