2

I've been tasked with writing SAD's for our current two projects and there are many more coming, all similar although different in small ways, mostly technical (they all have a similar requirements)

Let's first establish what I think an SAD is for: to provide a software design that satisfies functional and non-functional requirements with key use cases (4+1 model) to validate the design and various viewpoints for various stakeholders.

Primary reason we now decided to have SAD's is because after reviewing these projects, we realized our developers need some direction on what to use, when and how.

My question now is: is it wise to have a master SAD or reference SAD that describes project overarching requirements common to all projects (transactionality for example or prescribing a specific framework to realize IoC/DI).

Are there examples of this approach? A classical 4+1 model view wouldn't work, because such a reference SAD would not include a concrete Use Case or Class. As such, a reference SAD would not actually design a specific system, which is kind of why SAD's exist in the first place.

What I'm looking for is to describe once our common needs (package structure, tiers/layers, frameworks to use), while individual projects can minimize their copy/paste factor by referencing this common document and only provide Use Cases to illustrate and validate, class diagram and physical/deployment view.

To give you an idea of what we're dealing with here, the differences between these projects are of the following order of size: mostly microservices or small webapps (all the same frontend tech) with none to small sized domain models, either a rational database or a document store. Some have REST, JMS, SOAP or a combination going in and/or out. All projects are some combination of these things and they are all implemented using the same frameworks and approaches.

I prefer not to copy paste SAD's just to change a few details. I've also thought of writing an SAD for a virtual project or define "profile" SAD's to reference to. Or some other "modular" way of plugging together SAD's?

I would love to gain some insight on how to deal with many similar projects in a homogeneous way so our developers know what to do.

/edit: the more I think about it, the more I feel a reference SAD cannot properly capture concrete application needs. They're just too specific for their use case. Maybe it's better to switch to multiple similar SAD's after all and try to move out as much as possible to a coding guidelines?

Improve this question
4
  • What's the difference between your reference SAD and what is traditionally known as coding guidelines? The guidelines do not just handle spaces and formatting, but also the things you mentioned (DI, REST, JMS, ...)
    – Frank
    Commented Aug 1, 2016 at 6:09
  • @Frank Good question, I'm not sure there is. Although, the SAD would contain a Process View which would demonstrate transactionality or asynchronicity, for example. It also contains a tiers / layers prescription. I'm no sure that would sit well at home in a coding guidelines.
    – Benny Bottema
    Commented Aug 1, 2016 at 7:13
  • What would be the alternative to a master SAD or reference SAD, if you intend all projects to have the same architecture as much as possible?
    – Bart van Ingen Schenau
    Commented Aug 1, 2016 at 7:53
  • Coding standards are a great idea. However until tools could automatically enforce the standards, they tended to evolve into little more than dusty tomes. The problem was coding standards would inevitably grow so large that nobody could remember all the rules so eventually few people even bothered trying. Your SAD sounds like it is going to meet the same fate. Regarding architecture; training and developing common "core" libraries that follow desired practices would probably be more beneficial. Don't develop the libraries and say "use these". Let them evolve over many projects.
    – Dunk
    Commented Aug 10, 2016 at 18:46

1 Answer 1

Reset to default
1

There is nothing wrong with writing some sort of baseline document where you specify what to use when. However, I suggest you do not call it a SAD. It is also not really a coding guideline. Instead call it a Best Practices Guide. Also have a coding standard in place. This covers what you are trying to put in there and prevents confusing discussion about master SAD and reference SAD. Then for each application you would still write a SAD, which references the Best Practices Guide and the coding standard.

As a side note, you might encounter some fierce discussions about the Best Practices Guide and the coding standard, depending on the culture within your organization.

Improve this answer

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