When I write the book - Software Development Edition
February 2, 2017 12:45 PM   Subscribe

Let’s say you are managing a Widget System project that is in the O&M phase. Let’s assume it’s waterfall SDLC and Widget System periodically goes through bug-fix and enhancement releases. What is the best way to manage the system design and requirements documentation?

Option A: You update a system level requirements/design document with the changes for each release. You produce a RTM and/or change history so stakeholders know where to go to see what’s changed. The benefit here is maintainability since all changes are documented in one place.
Option B: For each release you create a new requirements/design document that has only the changes contained in the release. The benefit here is ease of use so it’s easy for stakeholders to understand that scope of what’s changing.
Option C: Some combination of the above
Option D: Something else

For the purposes of this question, assume Agile/Scrum/whatever is not an option. I’m seeking personal experiences as well as sources such as software development blogs or ieee or something.
posted by seesom to Technology (3 answers total) 4 users marked this as a favorite
One way that worked ok for us pre-agile: The new release requirement docs (which we called "features") were appendices to the system arch docs. However, part of release readiness was updating the actual technical and operational docs with the changes introduced in that release.
posted by forforf at 3:13 PM on February 2, 2017 [1 favorite]

In days of yore, we had requirements and design docs for every feature, and we kept them up diligently--after all, they were the system of record for questions about the feature. But as time went along, we moved to other systems, other philosophies, and we are now (kind of) Agile. Requirements and Design and PRDs in JIRA. Are they up to date as things change? My confidence is not high. I miss the old days, with Docbook docs on a central server, you could search and feel good that they were accurate. So if I could choose I would like your Option A. But you must be ever vigilant!
posted by Kafkaesque at 5:29 PM on February 2, 2017

Ok, I wrote a long post that started off "can you quit and go work for an agile shop?" And deleted it.

Ok. Given your constraints, I'd write this in JIRA, divided up into use cases (or user stories, whatever) that are all built up front (waterfall) but are easily able to be built out/modified/divided into dev phases or cut.

I presume you'll have separate test scripts for QA? Another way to do this is to build from the test scripts/acceptance tests. In the right circumstances, that can help people focus on what's critical and let the developers manage the rest. I think worst case scenario is when people higher up the food chain try to over-specify and over-design during waterfall, leaving dev and UX folks to quibble over the details. It generates infinite bugs ("this was supposed to be lime green! Why is it forest green?") and wastes build time.
posted by instamatic at 6:01 AM on February 3, 2017

« Older A list of lawyers to fight Trump's immigration ban...   |   It's processed, but it's not processed Newer »
This thread is closed to new comments.