-2

My question is related to designing new software. Let's say I work in a medium-sized company that has a core product. Now we want to start with new software (purpose of the application is different than the core product) with a completely different approach. There is a document with the main features from business point of view.

Now I think we should specify a solution and at least not last we specify language, libraries, etc. Am I right? If so, how to do it? I know how to document the last part with UML, use-cases, etc. But how to document that we want the software to be able to run as standalone service, a replicated service in a cloud, need of authentication, etc.

Is there any standard, methodology, or something?

Robert Harvey
  • 200,592
Majlanky
  • 119

2 Answers2

1

Is there any standard, methodology, or something?

There is and there isn't.

There are many differrent approaches to documenting software specification, requirements and architecture. Many of which claim they are the 'standard' way of doing things. But because there are so many of them, none is accepted by majority as the best way of doing things, so none of them can be considered a 'standard'.

Deciding on which approach best fits your needs will highly depend on your process and how your stakeholders want to approach the development.

Euphoric
  • 38,149
0

Starting point

You have a document describing the main features that are expected from the software. There are many suitable methods and techniques to continue, but their relevance depend heavily on the approach you intend to take.

Plain old waterfall, really?

Now I think we should specify a solution and at least not last we specify language, libraries, etc. Am I right?

Specifying a solution based on some high level business requirements is a daunting task and it shares some commonality with looking in a crystal bowl. Because the devil is in the details that you do not yet know, that your marketing people have no idea of, and even the best customer is maybe not yet aware of.

If nevertheless you'd like to continue on that path (I hope not, at least not in view of your narrative), the first step would then be to analyse the requirements with some business experts, write a detailed IEEE 830 software requirement specification. Then get it approved, with the risk that its implications for daily business is not well understood, and that obvious features are missed because for the readers it's so obvious that they assume it's for you as well.

Finally you can write an IEEE 1016 software design specification, with the full scale of UML diagrams as well as user interface description.

Then you start coding. But by that time, your competitors are already on the market. And when you'll deliver, you might discover that at least on some aspects it was a near-miss, and despite your mass documentation, your product is less appealing than you hoped.

A more dynamic and pragmatic approach ?

You need to discovery the needs and features that are required to deliver a nice product. This is best done using an agile -- or at least an iterative -- approach: at each iteration the users can refine their needs based on a product they can see.

The key is to capture all the requirements. In this context, three techniques stand out:

  • user stories, based on user expectations;
  • user story mappings, which is user stories, but structured in the beginning of the project to avoid a long flat list of stories that are difficult to relate with each other;
  • use-case 2.0, which is an agile practice to capture user goals and identify use-case slices (implementable parts) in a very similar way than user-story mapping.

User-stories tend to remain snapshot historical documents that are not updated once they are developed. Use-Case 2.0 and story maps add a structure that persists throughout the product lifecycle and make it easier to keep an up-to-date vision on the features.

Architecture

Whether you believe that architecture emerges by itself, or that key elements of the architecture shall be defined early, architectural sketches may help the team to discuss, will facilitate keeping an overview on your product, and will accelerate the onboarding of new team members.

Sketch them as needed in your development process, whether it's main components, important classes and interactions between them. Maybe other diagrams can help as well. But it should stay simple (i.e. sketch-grade): detailed class modeling with all the properties and functions is quickly obsolete, whereas the overall structure and main properties usually stabilize quickly after the initial iterations (and easier to update if there's a need).

Conclusion

Documentation contains useful content, only if it is really used (because when people really read or discuss it, they will correct what's ambiguous). Therefore, don't try to document what is already documented in the code: in case of doubts, this is where the developers will look anyway. Focus the documentation on what is not obviously available in the code and what emerges from the interactions. Because this takes the longest to understand, and is the most urgently needed when newcomers join the team or when the developed product is handed over to a maintenance team.

Christophe
  • 81,699