2

After years of experience in software development, I've not yet come up with a best practice for documenting business & technical decisions and requirements.

For instance, I want to know why we made the decision to implement a module in a way and why we changed it afterwards. This documentation could be used by new comers to the project and also other member of the team to recap the reason behind the decisions.

On the other hand I want to know what business decisions we have made and have a record of the changes with details.

So far I have used typical tools like MS word, excel, having pictures etc.

But I feel there has to be a pattern or practice for medium and large scale projects which could be more maintainable and usable.

Any idea?

Improve this question
5
  • I'm voting to close this question as off-topic because questions seeking software or toolset recommendations are off-topic because they tend to become obsolete quickly. Instead, describe your situation and the specific problem you're trying to solve. If you edit the question to focus more on techniques for retaining and retrieving decisions etc. it could avoid closure.
    – Marv Mills
    Commented Jun 9, 2015 at 11:59
  • 1
    Sounds like a lessons learned/closeout function. Or Project Management Information system. Or Organizational Process Assets. I'm not sure there is a good answer to this, but I think it is in scope.
    – MCW
    Commented Jun 9, 2015 at 12:37
  • 1
    As written, I think this question is on-topic but too broad; the questionruns the risk of being a polling question. What processes or controls have you tried already, and why didn't they work for you?
    – Todd A. Jacobs ♦
    Commented Jun 9, 2015 at 14:58
  • @CodeGnome As a matter of fact, I am developer and not a project manager. But I thought this question is best to be asked here because this should be a big concern for project managers. So far I have only used plain text format and some medias like images and videos and so on. I have worked with many companies remotely but I have not seen anything difference. For instance, when I ask why did you make this decision, people say that was a couple of years a go and nobody recalls why. Or Some times this is said to go and read a couple of hundred pages to see why!
    – Mori
    Commented Jun 9, 2015 at 15:41
  • @CodeGnome I will appreciate if you just give me a clue or some references to see how you manage this kind of stuff.
    – Mori
    Commented Jun 9, 2015 at 15:42

3 Answers 3

Reset to default
3

Tracking Specifications and Strategic/Architectural Decisions

I want to know why we made the decision to implement a module in a way and why we changed it afterwards.

This can be driven at several levels. I will address the project management and engineering levels, but for a deeper dive into how to track these things as an engineering process you should ask on Programmers Stack Exchange.

Project Management Artifacts

From a project management standpoint, this is one or more of:

It may even be a combination of all three in some cases. Versioning specifications may or may not actually be valuable, except perhaps in waterfall environments where everything requires a change request. In an iterative development model, scope and specifications are expected to change over time, so there is typically little to no value in looking at historical versions of requirements or strategic decisions.

Engineering-Level Artifacts

From an engineering standpoint, team decisions about code or architecture belong in engineering artifacts such as:

  • Use-case diagrams or narratives.
  • Comments in source code.
  • README files.
  • Team wikis or other information-sharing tools.
  • Completed user stories.
  • Acceptance-testing artifacts like Cucumber scenarios.

If you keep these things in a document repository or under source control, you can compare historical versions if you ever find that needful. This is rarely of value in iterative models, but your mileage may vary.

Improve this answer
3

Many of the design or project management decisions are the result of "trade-off analyses", and trade-offs are a method for validating requirements and/or designs.

A sound Systems Engineering approach to projects would yield these Validation artifacts daily, as time progresses. Without having to remember what the reason was.

Configuration Control processes also allow and ask for documenting the changes (and their effects).

SE practices are occasionally bypassed, to gain time and to get outputs faster. This makes tracking past solutions more difficult and the projects become more "people-oriented", where the existence and availability of talented and experienced designers/developers affect the project vitally.

Issue management systems also allow collection of tremendous amount of lessons as design matures. However, at the first stage of employing Issue Management, the problems are fixed without much lessons about the picture. But as project evolves, management may start to search for deeper solutions rather than daily solutions. But this depends a lot on personalities and openness to criticism.

Improve this answer
1

Most SE frameworks differ between what (requirements) and how (design). Fore sure, all design decisions should be linked to a requirement. If new findings come up, e.g. during implementation, should find their way back to the design document or even the requirements documentation.

Up to a design decision (left or right turn) you usually have some kind of documentation, e.g. meeting minutes, photos from a white board. If you reference those data within the design document, gold plating is avoided while it is still possible to understand design decisions.

Even it feels uncomfortable, having a documentation from what to implement and how to implement reflecting the implementation, incl. decisions and reasoning, is essential for lessons learned, analogous estimation, and so future project success.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.