Software Documentation

Software documentation is any written material that explains how code works, how to use it, or why it was built a certain way. Good documentation reduces onboarding time, prevents repeated mistakes, and preserves institutional knowledge that would otherwise live only in the heads of the original authors. Documentation is not one uniform thing, though — different audiences need different kinds of information, and conflating them (for example, writing API reference material inside a README meant for new contributors) makes documentation harder to find and maintain.

Code comments and docstrings live directly alongside the code and explain the 'why' behind non-obvious implementation choices, or describe a function's inputs, outputs, and side effects for anyone reading or calling it in an IDE. They are aimed at developers actively working in that specific file or function, and they should be kept close enough to the code that they stay in sync with it — comments that explain what the code obviously does, rather than why a tricky decision was made, tend to go stale and add noise. API documentation describes the public contract of a library, service, or endpoint: what operations are available, what parameters they take, what they return, what errors are possible, and any usage constraints such as authentication or rate limits. It is aimed at consumers of the API who may never read the underlying source code, so it needs to be accurate, complete, and often includes example requests and responses. README and onboarding documentation sits at the root of a project and answers the first questions a new developer or user has: what does this project do, how do I install and run it, how do I run the tests, and who do I ask for help. It is a map, not an encyclopedia — it should link out to deeper documentation rather than trying to contain everything. Architecture Decision Records (ADRs) capture significant design decisions at the point they are made: the context/problem, the options considered, the decision taken, and the consequences and tradeoffs accepted. Unlike a README, which describes the current state, an ADR is a historical record — it explains why the system looks the way it does, which prevents future engineers from re-litigating settled decisions or accidentally undoing them without understanding the original reasoning.

Notice how each artifact in the example targets a different reader and stays scoped to its purpose. The docstring and the inline comment serve someone reading or calling calculate_shipping_cost directly in their editor: the docstring gives the formal contract (types, error conditions, return value), while the inline comment explains the non-obvious 'why' of the discount branch — pure restatement like '# multiply weight by rate' would have added noise instead of value. The API documentation excerpt is written for a consumer who will never open this Python file at all; they only need the HTTP contract. The README excerpt is deliberately shallow — it gets a new developer running the code in three steps and then points elsewhere rather than duplicating the API or architecture details. The ADR is the only artifact that explains why the tiered-rate design was chosen over the simpler flat-rate alternative; if that reasoning lived only as a code comment, it would be easy to miss when someone later considers 'simplifying' the pricing logic back to a flat rate without realizing that decision was already made and rejected for a documented reason. Keeping these four types separate, rather than merging them into one giant document, means each one stays a manageable size and each reader finds exactly the altitude of detail they need.