Figuring out what to build is the goal of the brainstorm and design engineering process. Figuring out the specifics and defining them is the point of requirements (what exactly the software should do) and the specifications (how we might roughly go about it organizationally). Architecture which follows gets even more precise on the how getting to the system and code level. Our goal with reqs and specs is a bit more high level, but we see that very quickly we can forget about users, become impatient, avoid important details and start relying more and more on assumptions.
A simple sketch of a UI or an algorithmic outline is easier to revise and work out issues than laying out code.
People may resist planning because of impatience, time pressures, and it is not likely as rewarding as writing code (this may include the assumption you aren’t making progress by bosses)
Tip - Do you planning in comments or the Repo somehow?
The Who, What, When, Where, Why and How are the same things we need for requirements for software as well as for constructing something, baking something, writing a story, solving a crime, etc.
Ask the 5Ws and 1H or whatever other common approach to properly focus on what is needed. If you just focus on the H part (How) particular our approach you’ve under thought it and are too solution focused as opposed to user focused.
If you skip requirements that doesn’t mean there aren’t any just that they aren’t defined in an a transparent manner. In other words the requirements might live in some boss, stake holder, or customer head only to be revealed when your software meets or fails them might you start to get a clue of those requirements
Given the risk involved SEs should be involved in the creation of requirements or at least the verification of the requirements
We must translate from people often unskilled in software to the precision we need to build software
The requirements are more for us than to be clear than as some transcription of exactly what they said.
It is interesting to note that the lack of precision in user provided requirements and vague language use and how customers may then be dissatisfied with our software because we didn’t understand what they meant isn’t that unlike prompting an LLM system with a vague prompt and being surprised that it didn’t produce the exact code we wanted. Maybe by using these systems we can gain more empathy of users and also be more precise in our language use for problem description.
The truth is you’ll have both in your project such as “it needs to look clean and modern” and “the app must load in < 1second”
Obviously it is much easier to measure our progress towards precise quantitative requirements and you should have many to guide your efforts, but accept that some requirements will be more qualitative.
When faced with qualitative requirements try to add some quantitative aspect to steer. Ex: High Security → No major vulnerabilities discovered by a scan with tool X. Without this mapping you run the risk of some assumption of the meaning of the qualitative statement. Adding a metric will help you uncover some shared yardstick
Application: Make sure you can identify poor requirements and write or rewrite requirements into more concrete and hopefully quantifiable requirements.
Depending on your projects time and risk there is a range of formalism you might adopt from a few simple documents and a set of user stories to structured templates
There will be no single best way to document your system’s requirements, so figure out what culturally is required in the organization you find yourself in. Ex: there might be a vast difference between the highly structured docs before coding in a DoD project than a start-up which may lack much of anything.
Don’t assume one degree of formality is right and one is wrong, just that one is more appropriate than another in a given context with different practitioners.
The most important thing about documentation is often less the particular approach but whether the formality is appropriate and the approach applied consistently.
Visuals often communicate more efficiently than words, your requirements and design documents will likely have both things
Diagrams are commonly used to describe system architecture and flow
Common diagram types include:
Flowcharts
UML Diagrams
C4 Diagrams
Sadly mostly we find less commonly employed diagrams and more Ad Hoc Boxes and Arrows which is better than nothing, but our industry might benefit from shared blueprinting thought
Diagrams are also commonly found in interface specification
Wireframes
Interface Flow Diagrams and Clickable Prototypes
Be very cautious with making your interface diagrams too high fidelity otherwise people may over focus on colors or style choices rather than key requirements and decisions
Tip: Keep these things in your repo or very near your repo (project wiki)
As developers we often think in code and features, this is of course not how users think
User tend to think in needs, wants or as some like to say “jobs to be done”
One way to think of jobs to be done is “I use <think> because it helps me to accomplish <outcome>”
Notice how we have just defined Agile’s user stories here! Write user stories and use cases and always think of real users in mind as we define our software.
Notice how the jobs to be done is somewhat more focused on a user mental model discussed next.
The system model is how we tend to think of our code and present it it is in a sense our mental model as devs.
System models tends to focus on data and feature thinking and is helpful to organize code, but unhelpful to users how to accomplish their “jobs to be done”
A user model is how the user thinks of a task/product and is often more function based and less feature or software based.
Spolsky’s cardinal Axiom suggests that we focus on User Model > System Model
An example was given with a Web Application Firewall (WAF) called SeverDefender that employed a system model and failed at first despite being technical superior. Applying a user model to the situation change that outcome and was a tremendous simplification interface wise (though not technology wise). A key point from the story should be that the architecture of the system allowed for us to rectify the system model - user model gap, very often that isn’t possible so I generally strongly encourage you to work user model (often interface) downwards. Do note I was attempted to follow user model, I just listened to domain experts and non-representative users too much :-(
Admit that your software is much greater than just code (Software >>> Code)
The information that is important in software includes our plans, diagrams, user stories, meeting notes, internal docs, external docs, test cases, etc.
If we keep all these things spread around we are unlikely to keep track of everything well and may lose data over time. The loss of data about the software and code can be devastating to the long term success of the software. If the info spreads or is lost or fuzzy because it is only in people’s heads the software is in effect “dying”.
A suggestion in this course is to keep everything in the repo or repo + wiki as our single source of truth (SSoT)
If we make our specifications and requirements very very precise we might see a possibility of generating code from such things.
Formal definition though is harder than it looks and might be difficult to do especially in a world that wants to change things all the time
At this current point in time (2023) the use of ML based prompt systems should show a possibility, but also reveal some of the downsides as well! These systems are looser especially the way we prompt them than a formal specification translated to code.
It is far easier to work out our thoughts before we start building. The reqs and specs should be defined and the architecture eventually hammered out as best we can. We must be careful not to over do it lest we lose agility, but we must do some of these activities before we start otherwise we add massive risk to our projects.