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.

In my experience, software documentation standards makes cross-team collaboration within entire companies and departments much easier. We can make design decisions faster and avoid simple programming mistakes.

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.

Here are some commonly used software documentation standards: Design Documentation: Design documentation describes the architecture, components, modules, and interfaces of the software. API Documentation: API documentation focuses on documenting the application programming interfaces (APIs) provided by the software. Test Plans and Test Documentation: Test documentation covers the planning, execution, and reporting of software testing activities. Maintenance and Support Documentation: Maintenance and support documentation includes instructions, guidelines, and troubleshooting information for maintaining and supporting the software. It covers error handling, maintenance procedures, system administration, and troubleshooting guides.

As an AI language model, ChatGPT can assist with various aspects of software documentation, including following software documentation standards. While ChatGPT can provide guidance and information related to documentation, it's important to note that it does not have direct access to specific software documentation standards or organizational guidelines. It can, however, provide general advice and recommendations based on its training data.

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?

Gain a clear understanding of the project requirements, goals, and constraints. Consider the nature of the software, its intended audience, the development methodology, and any specific industry or regulatory requirements that may impact the choice of documentation standards. If your company has specific documentation guidelines or templates, take them into consideration. Ensure that the selected documentation standards align with your organization's practices, policies, and quality assurance processes. Consider the complexity and scope of the project. Larger projects with multiple stakeholders and extensive functionality may require more comprehensive documentation standards. Smaller projects may benefit from lighter documentation.

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)

Clearly define the goals and objectives of your documentation. Determine the specific types of documentation required, such as requirements specifications, design documentation, user manuals, or API documentation. Understand the purpose and target audience for each documentation type. Develop a timeline and schedule for each documentation deliverable. Set realistic deadlines, considering the scope/complexity of the tasks. Documentation should be treated as a living artifact that evolves alongside the development process. Continuously monitor the documentation to ensure it stays up to date with changes in requirements, design decisions, or code updates. Regularly review and revise the documentation to reflect the latest project developments.