What is the best way to manage changes and revisions in your software design documentation?

Version Control System (VCS): Use a version control system like Git to track changes in your documentation. This allows you to keep a history of revisions and easily collaborate with others. Documentation as Code: Treat your documentation as code and store it in the same repository as your source code. This ensures that documentation is versioned alongside the code it describes. this way you can collaborate with other developers on your documentation using the same tools and practices that you use for code. This can help to ensure that your documentation is consistent and up-to-date.

Managing software design documentation is crucial. Using a VCS like Git helps track changes and facilitates collaboration. Storing the documentation alongside code in ensures proper versioning. Integrating with tools like Jekyll, can be beneficial. Jekyll transforms plain text into static web pages, enabling the documentation to be easily searched, navigated, and viewed. For projects that involve APIs, adding Swagger provides a structured way of documenting APIs. Swagger offers a user-friendly interface to interact with the API’s resources without having any of the implementation logic in place. By leveraging Git, Jekyll, and Swagger, you can establish a robust system to manage, display, and interact with your software design documentation.

Your code is your least faulty and latest document. Someone may forget to update the document or cannot see the version history of document but can see the changes in code. So, write code like it will be maintained by others and not you. If written well and supported by well-defined process and tools, code will be best document.

Focus areas: - Source Control of the Documentation - Keep the collaboration enabled (comments, reviews, share) - Proper Document Review Process - Keep the Versioning (in e.g. V1.0, 1.1,...) Use the proper tools that come in handy: 1. Confluence (has all above) 2. GIT 3. CMS (Wordpress, Joomla, etc)

The best way to manage changes and revisions in software design documentation is to use version control systems such as Git. Store your documentation in a version-controlled repository alongside your code. Create branches for new features or changes and commit updates as needed. Use descriptive commit messages to track changes. Additionally, utilize collaboration tools like GitHub or GitLab to facilitate discussion and collaboration on the documentation. This approach ensures a structured and organized way to manage and track changes while enabling collaboration among team members.

Treat software design documentation as a living entity. Use version control like a "Documentation Garden" to track changes. Just as a garden needs care, your documentation needs regular updates. Version control alone isn't enough. Foster a "Documentation Dialogue" for team discussions and shared understanding. It's not just about versions; it's about collaboration. For example, think of a city master plan. Version control tracks changes, but without meetings, chaos ensues. In software design, combine version control with collaboration for success.

We have used a variety of documentation tools and standards e.g. IEEE software engineering standards. However, we found that while it could document features and functions, etc., it didn't work well for adaptive development processes. We typically have three levels of documentation: - Product overview designed for non-technical readers. - Software design documents as a brief to technical users, which extends the product overview. - Incode implementation documentation. The focus of the documentation is to appropriately brief a person who needs to maintain or update the module who was not part of the original implementation team.

Sometimes it is tedious or not so interesting to create document. So, it is important to generate document from code. Spring boot gives to create open API document based on swagger specifications. When you write code, check for API generation and put it as part of your code review process. Documents generated from code is always latest and greatest.

Two tips: - Always try to be as concise as possible with the docs. The more concise the doc is, the easier it is to update and read. Follow the KISS method as you start and edit your docs. - Keep in mind that the reader won't have your background about what you are trying to document, a short intro to enrich the reader's context before starting the doc is always appreciated.

The further the thing is you are documenting (e.g., code) from the documentation and the harder you make updating the documentation the higher the probability is the documentation will be done "later". Tools like Doxygen or Markdown let you put your documentation very near if not in the same place as code. This won't guarantee anything, but if developers don't need to context switch in order to maintain and write documentation you have a fighting chance.

Consider video recording. When you explain to a newcomer a new system, use Zoom or the like to record it, then share the video as part of the documentation. Cons: hard to maintain. Pros: cheap to produce and very communicative.

Although written articles are always the norm for most software docs, you should explore catering to other ways of learning, like making videos and workshops. Check the VAK learning model. Each member of your organization has an optimal learning style, and catering to their needs (e.g., using code examples, workshops, and videos) will result in highly engaging documentation. It is tedious to create multiple forms of documentation for the same topic, so keep that open only for high-level cross-org topics.

At my company we maintain a set of High Level Documents (HLD). These documents are maintained by specific Software Architects who keep system development focused. When new features are being designed, the impact is assessed and the impacted HLDs are updated to maintain development consistency. One of the most important goals is to have consistently designed and implemented software that comports to our development goals. By doing this we have up to date documentation, consistency in development, and reduced tech debt.

Our main product is around 350K lines of source code. We always do in-code implementation documentation, when creating or changing modules. e.g. describing the logic of the execution process as incode comments. Then publish using Doxygen We use Atlassian Confluence for technical overview documentation, so all members of the implementation team can access and update it appropriately. We use Atlassian Confluence to flesh out products or module scope and feature requirements. Both technical and non-technical team members have access to these documents.

Few things, which have worked for our team are. 1. Integrate documentation task as part of each sprint/iteration. e.g. Design, Implementation, Test, & Documentation. 2. Keep low level details of your design in the source code. e.g. Don't mention methods and variables in the class diagrams in SDDs. 3. Keep referring to documents for explaining/ understanding the design or requirements. This will push authors to always keep documents up to date.

For a maintainable documentation tool consider a Gherkin-format suit of behavior tests. If written properly, these tests provide documentation of the expected behavior, while also functioning as living, runnable tests that fail when the behavior changes. Here is a simple example (copied from @mytag Scenario: Add two numbers Add two numbers with the calculator Given I have entered <First> into the calculator And I have entered <Second> into the calculator When I press add Then the result should be <Result> on the screen Examples: | First | Second | Result | | 50 | 70 | 120 | | 30 | 40 | 70 | | 60 | 30 | 90 |

You're developing a project management app. During beta testing, you gather feedback from users, developers, and stakeholders. Users: They find task assignment confusing. Developers: Suggest optimizing a feature for better performance. Stakeholders: Advise focusing on mobile accessibility. You validate these points: Redesign the task assignment feature based on user feedback. Optimize the feature as developers suggested. Prioritize mobile access per stakeholder advice. After implementing changes, you collect another round of feedback to confirm improvements. The result is a more user-friendly, efficient app that aligns with stakeholder goals. This iterative feedback loop enhances the product, fosters collaboration, and builds trust.

All of our product features are derived from the user's real-world environment and workflow. Mapping the user's workflow and data usage provides a detailed picture of the real-world environment. We find a lot of technology products and packages map the data well but often don't include non-technology aspects of the real-world environment and workflow processes that can affect the user context within the process. E.g. provide a method of saving incomplete page data, because the user needs to collect additional information to complete the page fields.

Peer-review is an example for this case as well. Your teammates review the document and give you feedback. This improves document quality before you share with other department

Use "real titles" for commits. Not "Update to foo.c" They should explain what was done in shorthand without going further into the commit.

Getting sign-off or announcing a status update to documentation is always a great practice to helping users understand that documentation is both maintained but also that it is EMPHASIZED as a tool to aid in knowledge transfer.

Agree: A VCS is indispensable for tracking changes and facilitating collaboration. It ensures that you always have the most current and accurate version of your documentation. Best Practices Add: Documentation Standards: Establish a set of guidelines for how documentation should be written and formatted. This ensures consistency. Change Log: Maintain a detailed log of what changes were made, why, and by whom. This provides a historical context for revisions. Review Cycles: Implement periodic peer reviews to validate the documentation. This can catch errors and inconsistencies early on. Automated Tools: Use automated documentation tools that can update sections of the documentation based on code changes, reducing manual effort.

Store Documentation with Code: Keep your documentation in the same repository as your code. This ensures that documentation is versioned alongside the code it describes, making it easier to maintain consistency.

Understanding the importance of documentation is at times hard for alot of people. At times even leadership or owners of small companies also tend to focus on the product output only. So rather than thinking documentation as a overhead, people should take documentation as a tool, which not only help them in remain compliant with regulations but also in improving product quality.

Before plunging into documentation, consider User-Story-mapping. - Who are your documentation users? - What are their pains? - How frequently will they use the documentation? with what urgency? - What would delight them? - What is their journey from the problem (e.g. I don't know how to install and need to have the system working) to happiness (e.g. The system is installed and working on my machine) Once these are clear you can start implementing the documentation system.

Here are some additional considerations that could enrich the conversation on managing software design documentation: Documentation Ownership: Assign a dedicated person or team responsible for maintaining the documentation. This ensures accountability and focus. Versioning Strategy: Beyond using a VCS, have a clear versioning strategy that aligns with software releases. This makes it easier to track changes and understand the state of the system at any point in time. User-Centric Documentation: Consider creating different versions of the documentation targeted at different audiences, such as end-users, developers, and administrators. Audit Trails: Implement a feature that allows for audit trails in your documentation. T

Managing change is not the same thing as change management. One requires a holistic process and the other is just tracking changes to a single entity. Effective change management understands that all the artifacts that represent a product (code, documentation, tests, requirements, ICDs, APIs, etc.) are impacted by change. A robust process will account for these interdependencies in the records used to document a change (a git tracker or jira or whatever). Definition of done must include FULL change execution. Of course we have all been in that 11th hour of having to get a feature or fix out the door and say "code works, ship it". That's just technical debt in disguise.

1 coverage of requirements 2 diff between time-frozen releases/or internal milestones. That is: snapshot everything from requirements to deliverables at a moment in time. These are the basics. The rest follow naturally.