How do you benefit from software documentation standards in programming?

Documentation can include anything from code comments to user manuals and is an essential part of any software project. It makes it easy for future developers to understand and maintain and update. Good documentation can also help you learn from your mistakes, so you don't repeat them.

Having good standards minimizes miscommunication, reduces misinterpretations and improves product quality. It also helps programmers understand quicker- which may lead to quicker development.

I fully support that. It can be also a great way to help more junior programmers in your teams. As soon as they start picking up, you have a base you can work with.

Documentation needs to be useful. Standards are a great way to maintain consistency between documentation authors, but people should not fall into the trap of doing documentation for its own sake. It needs to be useful now or in the future, and if its not, consideration needs to made to why its not useful. This could mean the standards need adjusting.

It's beneficial even in the onboarding process, teams have to define specific documents about how they configure the project's environment, or what are their criteria and standards of development and even how the business works, because until a developer does not know what is the business and how its working, they cant develop a good software for that.

In our database solutions we add comment lines with creation date, developer, description. Example that we add to the SQL files of functions and stored procs /* 20230701 Jason V creation of a function 20230712 Jason V added extra tables */ Each edit is also added to the comments. We use GIT as source control but this doesn’t allow comments for each piece of code being checked in. In Devops we have a Wiki that has documentation on the architecture and the way the ETL works.

Always be verbose with variable names (no matter how long they get) and don't comment obvious lines unless there is value to the comment. Diagrams and figures can be very useful for team members who are more visually minded, but you should always consider their maintainability (especially for a system that changes often). Tools such as mermaid or bespoke json to figure apps can be extremely useful in this regard.

For object oriented languages, you can use UML for some diagrams. My preferred diagram is sequence diagrams because it helps showing the flow of execution. No need to use a sofisticated tool. Again simple and fast is great, like using plantuml.com, with some simple text you can get a great diagram.

Tools such as ChatGPT are providing increasingly good results regarding code comprehension. Try pasting some of your code and asking it to provide a description of what it's doing. (Careful not to paste sensitive or secret information)

It does not matter which position you are in, I believe project managers, senior engineers and product managers and everyone who has a higher position has to define some structures based on standards and when they start working on each project, they automatically start to develop required documents based on pre-defined lists and structures. this makes the handwriting of everyone the same in the project.

Think about: - Who is this documentation for? - How will they use it? - What information do they need in order to comprehend the system or make a code change? - How can we best avoid making this documentation go stale?

It's notoriously hard to maintain documentation. There are however certain behaviours and processes that can be followed to keep documentation from going stale. Some ideas are: - Review high level documentation with every PR into main (does this change affect the current documentation? Do I need to add to it? - Create regular meetings with your team (they don't have a to be long) to review the state if the documentation, and assign outdated aspects to different team members to address. - Don't be afraid to change your standards if you feel they aren't maintainable, or are not providing the same level of value. Rigidity here is not your friend. - Find aspects of the documentation that can be automated (provided this gives value)

Design Documents also help in identifying other areas of impact and thereby ensuring the release a minimal bug, or to take it further, a bug free solution as a release candidate.