How to track change requests over a functional document

Question

Functional requirements tend to mature as the time goes by, and the initial versions of requirements for a project are usually based on assumptions (otherwise the work would never start).

As the development cycles evolves, though, changes to the original requirements are required to be applied.

In this specific case, the development is still ongoing, based on a master MS Word document containing functional specs plus a lot of change request (properly tracked separately from the functional document).

Question: How to correctly track these change requests?

Assumption: The master functional doc should reflect all change requests (as that's the document to be used in the future for reference purposes),

Open point: I'm not sure if I should only spread comments over the original version, completely remove the updated pieces, use the 'tracking changes' functionality or have a rewritten Functional document.

Any thoughts?

Answer 1

TL;DR

Your assumption that you need to track changes across multiple revisions is limiting your scope of change control options. So is your use of the Microsoft Word format. I'd reconsider both unless you can:

• ensure you have a single document owner, and
• track textual changes independently of your change-control approval process.

However, if you can't change either your assumptions or your tool-chain, I've included some suggestions about submitting changes through a centralized document owner and implementing revision tracking that might prove helpful. Your mileage may vary.

Types of Document Artifacts

Living Documents vs. Baseline Documents

A living document changes as a project progresses. For example, a specification document may get updates when feature foo is replaced with feature bar, or when feature baz is modified in some way. This type of living document may have sign-offs or approvals, but isn't intended to be compared to legacy versions of itself and is therefore relatively easy to maintain.

A baseline document is an historical artifact. You might create a baseline specification at the start of a project, and then create new specification documents at need during the life of the project. All such documents are kept as artifacts of the project, but need not be revisions or even directly comparable. They are simply snapshots of the project's specifications at given points in time.

Bastardized Documents

I'm deliberately using the term bastardized documents instead of "hybrid" or "shared-editing" because the need for complex change tracking is generally a result of ad-hoc editing. For example, if you route a document around to 37 people, all of whom are free to make revisions directly to the document, those changes need to be merged, conflicts resolved, and some sort of traceability for the changes needs to be implemented.

Assign Document Ownership to Preserve Sanity

Free-for-all changes are generally just a Bad Idea™. I'd strongly suggest a simpler approach where:

1. Documents have a single owner.
2. Documents are line-numbered.
3. People can submit requests for changes, referencing line numbers as needed, to the document owner.
4. The document owner makes changes and submits them to the approval body at need.
5. If required, the change requests can be kept as historical artifacts.

Again, this is largely independent of the issue of change tracking within the document itself. However, actual revision control systems (think SVN or Git) can serve some of the same purposes and track the full history of textual revisions, too. More on that below.

The Value of Tracking Historical Versions

Whether there is actually any value in this is really a political question. From a practical standpoint, what the specifications used to be is less useful than what the product/feature needs to do now.

Version (or revision) tracking is really an independent issue from change control. For change control, you need to be able to define the changes (and perhaps the associated business cases) and get appropriate approvals for the new to-be specifications. If the changes are subtle, it's sometimes useful to see the as-is and to-be versions side-by-side so that the differences are more obvious, but the central feature of change control is that you're authorizing changes, rather than tracking historical versions.

With that in mind, you only need to track the most recently-approved version and the new (currently unapproved) version. This violates your assumptions as outlined in the original question, but may be worth considering.

Tracking Historical Revisions Separately from Change Control

How you do this is largely dependent on your technical implementation of process. If you must stick with MS Word, you might consider:

1. Always keeping change tracking on.
2. Add hidden notes attributing specific changes to people, meetings, or milestones that aren't captured by change tracking.
3. Hide the changes/notes unless you're doing some sort of document archeology.

This works up to a point, but gets messy and confusing fairly quickly. If you use a more flexible format such as OpenOffice or Markdown, or even just a utility to dump text from Word to ASCII at need, you can store textual revisions in a source control system like Git. Personally, I often use Markdown or AsciiDoc as the native document format so that I can store textual revisions in Git, and use Pandoc to pretty-print the documents in PDF, HTML, or Word format when needed.

This separates the complexity of revision control from the process of change control. It allows one to go spelunking in the revision history for side-by-side comparisons of any arbitrary pair of revisions, as well as the inclusion of notes and explanations in the history itself (e.g. Git logs or Git notes).

Example of Document-Owner Model with Revision Control

As an example of the document-owner model coupled with a text-based source format and a revision control system, consider the following. If Bob is the document owner, and Alice isn't savvy enough to edit Markdown or commit changes to Git herself, then Alice might submit a document change request to Bob saying:

Please change line 17 to say "embiggen the widget" instead of "minify the monolith."

and Bob can make the changes, attributing them to Alice, and submit the new document through the change control process for approval.

Word-Processor Based Options

Your mileage will vary a lot of you don't use a text-based native format, or don't use a revision control system. However, similar things can be done (albeit in a more limited way) with Word and LibreOffice documents, each of which supports various types of change tracking, document versioning, and version comparison.

If these features serve your needs, great! If not, at least you now have a few alternatives to your process or tool-chain that you can consider.

Answer 2

A common issue. There are a few approaches, but this is the one I use:

1. Each change, or set of changes is captured in a new Change Request document. The CR document must capture the new requirements in as much detail as is required to a) approve them b) perform the functional requirements analysis c) do a reasonable estimate of the effort required to deploy the change (not just the development but all the downstream impact of deploying the change). Make sure the right people in the development team are included in the review/signoff so they know what is coming.

2. Each CR is assessed by the project board/the business/the sponsor/whoever is most appropriate to determine if the cost of the change is worth paying given the benefits it will bring.

3. If the CR is approved to proceed it goes into the detailed functional analysis phase. Make sure you tell the development team it was approved so they know what is coming. The previously approved document is uplifted to a new minor version, i.e. v1.0 to v1.1 (taking care to keep a copy of the original version). Tracking changes is set on and the document is updated in all respects to cover the CR. In the edit history you reference that this new version contains the amendments pertaining to CRxxx and, fairly importantly, list the headline changes in the edit history part of the spec e.g. Section 1.2 changed to include the new widget, Secion 2.7.1 changed to include the new widget in the integration scope etc. etc. Send a copy to the development team so they know what is coming but make sure you make it clear at this point it is yet to be approved so no-one starts development yet.

4. When all the amendments have been made it needs to go for approval to the same set of people that approved the CR. They can use the change tracking to see exactly what has been changed, or view/print the document in Final without Markup if they want to. They review that all changes have been made and they are happy with the new version. The signatories to the functional spec also need to review the amended document.

5. Iterate in through as many review/change cycles as needed until the signatories sign off the changed spec. Then save it to a new copy, uplift the version number to the next whole number (i.e. from v1.3 to v2.0), add a line in your edit history section with a comment saying Approved Version AND ACCEPT ALL CHANGES. Save it to the central project location, archive all prior versions and distribute it to everyone that needs it with instructions that it supersedes all prior copies. Run through it with the development team, talk about the changes, plan the changes into the project and make sure the devs are all on-board.

I have seen this messed up on several occasions and it is usually down to the following reasons. Don't be tempted to try and short cut the process, eventually it will cost you:

1. The new changes are captured in a new spec just for them, which is eventually approved and passed to the developers in addition to the original spec. This is a nightmare- you will end up with different people developing to different specs.

2. People wave through the changes without documenting them, estimating them and properly considering the impact

3. People only ask the devs to estimate the changes/additions and forget to include the testing/QA team, and the hardware team, and the infrastructure team, oh and the release manager, and the BAs, and the MI team who have to deal with the downstream data and deliver changed reporting... etc. etc. Don't do this- Send the CR round to all the departments involved in the project so they can assess the impact of the change, then take that impact into account and cost it into the project budgets.

4. People don't keep a log of the CRs so once there are over three it all gets a bit confusing

5. People don't keep the paper trail of versions and CR documents so it becomes impossible in a year's time to figure out what was changed and when.

6. People don't ever go back and accept the changes and turn tracking off- So changes build up from version to version and eventually the document is impossible to read properly.

7. People say "let's just get the change in and we'll catch up all the document merges later"... It NEVER happens, and before you know where you are the project is specified in 23 different places each with shades of versions, understandings and estimates.

Basically deploy consistent change control, document and track your changes even if they get rejected. Keep, as far as is possible, one single central version of "the truth" and make sure everyone is working to it. This can become a ballache in its own right, but keep at it- no matter how arduous it gets, it will always be much much more of a nightmare trying to retrospectively understand what the spec was supposed to be in the absence of change control and a paper trail.