Are you happy with the current state of documentation on your software team, or are you looking to make improvements?

Software documentation is a continuous improvement process. Here are key areas we focus on:

A few areas of focus:

Authoring
 - Use common templates across the firm for consistency.
 - Follow industry standards like C4 and ArchiMate for software and architecture documentation.
 - Adopt formats like OAS (Swagger) for API documentation.

Governance
 - Implement a mature and consistent process for reviewing and approving documentation.
 - Keep documentation updates and software releases in sync through version control and change logs.

Management
 - Maintain a centralized documentation repository.
 - Enhance discoverability through tagging and systematic association with IT asset tracking systems like ServiceNow or LeanIX.

We are ok with documentation on the design and solutions. Typically use Confluence and Sharepoint for documenting design diagrams, solutions, roadmaps etc. Where i could see improvements is around API documentation. We currently use a mix of Swagger (Open API spec) and Mule (RAML based) to document our apis. Teams are using GitHub Copilot to generate Swagger annotations for existing resources. Where i can see opportunity to improve is on documenting with examples so clients for apis can easily understand and comprehend them. We talked about brining Shape into picture as well so have to see how it works out. In general what I have seen is if the API documentation is not close to the code and is not automated then it is hard to keep it up to date. 

Software development is a continuous process if nothing you are continuing to maintain the applications and TLM. Hence, documentation also is a continuous process in keeping current. Not satisfied but certainly a conscious effort to keep up with the system/application changes.

Some experiments I’m looking at to improve include developer education and accountability, exploration of GitHub Copilot to aid into generating documentation, governance checks, etc. It is also important to have a centralized documentation tools like Atlassian Confluence or other to ease developer/team collaboration in an organized manner.

Not too satisfied but it's coming along. We are adding more "white papers" to our documentation to cover specific business processes. We're having developers write these as they read through the code - this helps them understand the system and it helps Product/stakeholders to know what the baseline is before making changes to processes.

There is always room for improvement, and whenever new functionalities are rolled out, it is imperative to update the documentation to stay current. Maintaining up-to-date documentation is a continuous process with no end state, and it is the responsibility of the entire team, not just one person.