Specification 101¶
So you've read up on ESL and would like to start writing your own specification. Great! Sometimes starting out on your own can be difficult, but this page should contain some useful pointers to get productive.
What goes in?¶
If you're ever lost as to why you're doing what you're doing with your specification, remind yourself of the following:
Tip
Look at your specification as the most accurate overview of your scope with just enough context at any given point in time.
Let's dissect this statement!
Scope¶
Your scope are the things you desire or that need to be designed or built. These components and their requirements are probably the reason why you want to write a specification in the first place.
It's fine to start out with a "black box" with no subcomponents at all. Try to make a basic description of the box's goals with respect to its context or even resort to qualitative requirements first in terms of needs.
Especially in discussions meetings, it's much easier to agree on something rather trivial first, before diving deep and realizing you built on the wrong foundation.
Context¶
The context is that which is given. These components and their constraints describe how they "just work" to increase the understanding and traceability of the components and requirements in your scope.
The context forms a common pitfall for specification madness. People and organizations possess huge amounts of knowledge. The same probably goes for all related components that interface with your to-be-developed system. It might be tempting to include all components and subcomponents that you know of, even of related systems and already existing components. This is a common pitfall. It's not a knowledge dump! Don't create a model of the universe, stick to your world.
As a rule of thumb, only add components and constraints when you need to:
- Describe an interface with a component in your scope.
- Complete the flows through your scope's components such that all goal and transformation requirements can be traced throughout.
The first one is most often encountered in your world where you describe interfaces (goal
requirements) between your scope's components and the existing ones.
The second one usually occurs when using or interfacing with off-the-shelf components. For full functional traceability, you then include the internal workings (transformation and/or behavior constraints). This traceability means you can follow the flow of variables and their conversions throughout the components.
Point in time¶
A specification is not a one-time affair. You probably have a basic idea of the top-level components as you start off your endeavors. As time goes by, you start making (design) decisions and change your specification by adding or changing content. Reasons could be that you increase the level of detail, new requirements arise, requirements change, you decide to go down a different path, and so on.
There's a reason the V-model goes deeper and deeper as time progresses and iterations and deviations are made and consolidated in progressing stages. Since ESL is just plain-text, it's a breeze to use mature version control systems like Git or project management tools such as GitHub, GitLab, or BitBucket.