What are the best practices for documenting system changes and updates for future maintenance?

I always start any new process design with a high level, then a detailed flow diagram. Gathering customer requirements, personnel positions, and any key data points or outputs the customer requires. Once all stakeholders understand and agree on the process flow charts, them you can begin writing out the body of the process documents to support all areas in the process.

For maximizing doc readability and achieving high levels of alignment, it is important to include various comprehension strategies like process maps, step by step process description, and even RACI-type process descriptions so it is clear to all stakeholders what actions are taking place and which system or human is responsible for specific steps in the process.

Documenting rationale is absolutely must to understand the design and the changes otherwise changes don’t make sense. Rationale can also document the deviation from design or any other adjustment made.

I find it helpful to present information in terms of options, phases, tradeoffs and decisions that need to be made. It is vital to focus on the outcome to the customer when presenting the impact of system changes or updates.

Consider reviewing a publication "Intent Specifications" and information about SpecTRM located in the MIT web for Prof. Nancy Leveson. "SpecTRM emphasizes finding errors early in the development cycle so they can be fixed with the lowest impact on cost and schedule. The tool facilitates tracing not only requirements, but also design rationale (including safety constraints) throughout system design and documentation."

MBSE plays a critical role here. To allow dynamic traceability analysis and to make change impact analysis simpler, use an MBSE (more specifically SysML) compliant tool.

For those using Google Docs: To keep the review and approval process lightweight, I use Document Write / Review / Approve (DocWrap), which is a Google Docs add-on that automates managing reviewers and approvers of a Google doc, and displays the reviewed/approved status.

Traceability, validation, and verification all go together. During the days of rehosting, regression testing using previous acceptance test plan and verification that functionality met previous allocations was the starting point. Then the Functional Control Audit and ATPs were update to verify the change was implemented properly and a new baseline was set. It all begins with ensure areas outside the change area have not been affected, or if they have, it was intentional.

This is a great most to have best practice. However is not enough to document it. This will not yet be a lesson learned. It will be truly learned only and only if you implement a knowledge managment system... else, you may end just creating additional documentation that when required no one is looking or is aware of it. The lesson learned really needs to drive a change in processes (not only in a product)

When Systems Engineering is consistent, manages change, ensures traceability, validates and verifies, utilizes MBSE principles, and incorporate lessons learned ... as a multi-science discipline engineer in the System Safety Engineering world, my job is made a lot less difficult and all made easier for a program team to eliminate hazards, reduce management risks, and more importantly save lives.

ISO-9000 and DOD 5000,1,2 are GREAT guidlines best practices...plus most all USG contracts require compliance. Systems Engineering needs to be designed into programs from the gitgo! And will pay large benefits if followed through entire program life cycle!