Developing Dev's resource offers insights, tutorials, and resources for software developers and technology enthusiasts. Readers can learn about coding best practices, software architecture patterns, and emerging technologies. With articles, tutorials, and code samples, Developing Dev provides  guidance and expertise for building software applications and advancing technical skills.

The Developing Dev

While documentation is often seen as essential, it comes with several drawbacks such as high maintenance costs and the risk of becoming outdated. Documentation should be evaluated for its return on investment (ROI). Certain types of documentation, like high-level system diagrams and popular API documentation, can be more beneficial. Inline documentation is preferred for its ease of maintenance. Advances in large language models (LLMs) may soon provide dynamic, up-to-date explanations directly from the codebase.

The Case Against Documentation

Another case I would like to highlight is writing documentation before actually writing the code: in this case, the documentation (or specification) can be used to find and address problems earlier (before writing the code), and it also helps to align on the implementation with other developers. So, at the implementation stage, the specification is the source of truth, and once the thing is implemented, the source of truth becomes the code (but the specification can still be used to understand the high-level concepts of the solution even as the implementation moves on)

I am all for writing helpful comments everywhere in the code, especially when the logic is distributed between different files. This helps anyone maintaining to know what does what without reading the whole codebase distributed in different files.
Moreover, I like to use README files to writes policies for naming conventions, exception handling practices etc.
Google Sheets works best for API documentations in small projects.

Well, tests and types are documentation. Any live documentation is good documentation.

LLM’s are still unable to recognize system-level decisions. Huge fan of tools like mkdocs for writing in markdown.
I’d rather use LLM’s as a documentation “prettier” type tool at the moment.
I’m facing this as a problem now and I don’t know what’s a good standard.

Code and docs should live together.
Docs-as-code more specifically, not annotations in the code.
There should be a single source of truth. Disconnecting them, for instance with code in Git, and docs in whichever CMS, can only lead to a drift.
A feature, and a bit of code at large, should always be delivered in the same time than the corresponding doc update, whether that doc is purely internal or external.
Yes, that’s an investment in time and money. But think of the impact of someone leaving the company with their knowledge and having to onboard someone new to replace them. Or of any undocumented feature that external users can’t adopt. In both cases, that’s way more money lost.