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?

3 Answers 3


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.

  • 1
    Thank you so much. Your books were amazing, I read the first one and it was really helpful also I made multiple user cases. It also helped me think about the problem from different sides as well. Thanks.
    – Lostsoul
    Oct 9, 2012 at 3:09
  • -1: This is good advice for formulating requirements, but it doesn't help the OP improve his/her communication with fellow developers.
    – Jim G.
    Oct 10, 2012 at 1:19
  • @JimG. My point is that by learning the requirements and architecture processes, becoming better at understanding what requirements are needed by the developers, and by learning what goes into the high level architecture and design of a system, communication will be improved simply by a shared understanding of terminology and processes. The rest is on the shoulders of the developers to learn the domain and gain the domain-specific knowledge that is needed to understand the requirements and then create and implement the system design.
    – Thomas Owens
    Oct 10, 2012 at 20:05

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.

  • 1
    Thanks Jim, I didn't use metaphors as much because I find if its not a perfect metaphor than it can add to confusion but I did buy the back of the napkin book and made many drawings in my specs to explain and the developers did mention that it made the workflow/processes alot easier to understand. Thank you.
    – Lostsoul
    Oct 9, 2012 at 3:10
  • @Lostsoul: Please see my update.
    – Jim G.
    Oct 10, 2012 at 1:14

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.

  • Thanks Glen, I've been reading up on this and although not implemented, my goal this week is to include it into my specs. I honestly never heard of this before you mentioned it and thank you for bringing it to my attention.
    – Lostsoul
    Oct 9, 2012 at 3:11
  • -1: Too boring. I don't know where you work, but at places that I've worked, things move much too quickly for the developers to be "pushing paper" with some arcane "traceability matrices".
    – Jim G.
    Oct 10, 2012 at 1:22
  • @JimG. - The OP specifically said they were a hobbyist programmer and was struggling with his ability to explain the design to professional programmers. The RTVM is a solid tool for forcing focus in those areas where he was asking for help. It is a tedious tool that can generate a mountain of paperwork, but I alluded to that with It can be a bit tedious ... In this particular question, I felt the benefits outweighed the drawbacks.
    – user53019
    Oct 10, 2012 at 2:16

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