I’m really struggling with my software specs. I am not a professional programmer but enjoy doing it for fun and made some software that I want to sell later but I’m not happy with the code quality. So I wanted to hire a real developer to rewrite my software in a more professional way so it will be maintainable by other developers in the future.
I read and found some sample specs and made my own by applying their structure to my document and wanted to get my developer friend to read it and give me advice. After an hour and a half he understood exactly what I was trying to do and how I did it(my algorithms,stack,etc.).
How can I get better at explaining things to developers? I add many details and explanations for everything(including working code) but I’m unsure the best way I can learn to pass detailed domain knowledge(my software applies big data, machine learning, graph theory to finance). My end goal is to get them to understand as much as possible from the document and then ask anything they do not understand, but right now it seems they need to extract alot of information from me. How can I get better at communicating domain knowledge to developers?
I would suggest learning more about the upstream activities in software development, especially requirements engineering and system architecture. These two activities are the direct interface from the customer and user needs and environment to the person or people who are building software. These activities are not only directly derived from the inputs from the user and customer, but they also provide the inputs into system-level and acceptance testing.
When I was taught about requirements engineering and high level design, I was always taught to involve the right stakeholders from the sponsoring organization – the customer, the user, the people who will be maintaining the system, and so on. These people shouldn’t just be involved in making decisions, but also understanding how the system is going to be built and what will be needed from them throughout the project. Taking the initiative and learning these areas on your own would help with interfacing with people who will be building the software.
If you want specific resources, Karl Wiegers has two books on requirements engineering – Software Requirements and More About Software Requirements. I can also recommend two books on how software architectures and designs are created – Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives and Software Architecture in Practice.
3
Use metaphors.
From Herbjörn Wilhelmsen’s blog:
A metaphor is an analogy between ideas. We use metaphors to explain or understand something in terms of something else…
…Human thinking depends on metaphor. We understand new or complex things in relation to things we already know…
…Metaphor stretches imagination in a way that can create powerful insights…
Prominent computer scientist Fernando J. Corbató said:
The value of metaphors should not be underestimated. Metaphors have the virtue of an expected behavior that is understood by all. Unnecessary communication and misunderstandings are reduced. Learning and education are quicker. In effect metaphors are a way of internalizing and abstracting concepts allowing one’s thinking to be on a higher plane and low-level mistakes to be avoided.
From pp. 9-12 of Steve McConnell’s Code Complete 2:
Important developments often arise out of analogies. By comparing a topic you understand poorly to something similar you understand better, you can come up with insights that result in a better understanding of the less-familiar topic. This use of metaphor is called “modeling”…
…In general, the power of models is that they’re vivid and can be grasped as conceptual wholes. They suggest properties, relationships, and additional areas of inquiry…
…The history of science isn’t a series of switches from the “wrong” metaphor to the “right” one. It’s a series of changes from “worse” metaphors to “better” ones, from less inclusive to more inclusive, from suggestive in one area to suggestive in another…
…Software development is a younger field than most other sciences. It’s not yet mature enough to have a set of standard metaphors. Consequently, it has a profusion of complementary and conflicting metaphors. Some are better than others. Some are worse….
…Over time, though, the person who uses metaphors to illuminate the software-development process will be perceived as someone who has a better understanding of programming and produces better code faster than people who don’t use them.
In fact, McConnell speaks directly to your concern about using flawed or imperfect metaphors. [p. 20]
…Because metaphors are heuristic rather than algorithmic, they are not mutually exclusive… Use whatever metaphor or combination of metaphors stimulates your own thinking or communicates well with others or your team.
Using metaphors is a fuzzy business… If you extend them too far or in the wrong direction, they’ll mislead you. Just as you can misuse any powerful tool, you can misuse metaphors, but their power makes them a valuable part of your intellectual toolbox.
And after you’ve mastered metaphors, learn how to draw.
Dan Roam’s book entitled ‘The Back of the Napkin’ illustrates how the ability to draw can make anyone a very powerful communicator.
And you don’t have to be Pablo Picasso. You just need to be neat and thoughtful.
2
Start implementing RTVMs (requirements traceability verification matrix) for your project. It can be a bit tedious, but it really helped me wrap my mind around all of the different aspects of developing software.
An RTVM essentially looks like a giant V and essentially revolves around Why | What | How. Each lower layer provides the How for the Whys and Whats from the layer above. On the left side of the V, you’ll move through application requirements into module requirements into functional specifications. On the right side of the V, you’ll provide ways / means of how to verify the corresponding requirements of that level.
Some links to help get you started:
Requirements Traceability
Traceability matrix
Googling “requirements traceability verification matrix” will provide a lot of resources as well.
3