Next, ask him to add a new piece of work into that process, and see how he approaches it.
Finally, whatever he does, use the techniques he used to describe his old work to help him envision your code.
It is far easier to adapt pre-existing ways of thinking and working to a new topic than to ask someone to tear down years of habits and rebuild from scratch.
I've seen good sequence diagrams and good high level architecture diagrams, but nobody decent uses UML. It's far too cumbersome and at the wrong level for an explanatory diagram.
I think programming is an iterative approach. If he's experienced with existing codebases, adding features and bugfixing, the existing structure and design might still seem like "magic" - because someone else figured all that out. That historical process become "lost art" to those not involved. While most people can learn to follow a map, very few create the opportunity to sweat out the ability to be able to create the maps themselves.
In design, there's both a bottom-up and a top-down approach. Both are required for a software developer:
1) Have the person build a small meaningful project from scratch using the very smallest building blocks (ie. stdlib). Have them build on top of that again. Make them iterate on design and codebase. Refactoring becomes a natural learning experience in its own why and how.
2) Have the person design the simplest overall system architecture from memory as free-form drawings (or other preferred method). The fewer boxes and lines initially, the better. Have them iterate on adding details for components and subsystems. The idea should form how free-form drawing is natural and the results be usable in understanding, improving, optimizing, discussing and communicating.
3) Combine #2 and #1, preferably as free-form personal projects. Just this time you start with #2. Knowing #1 is solvable by iteration; iterate on #2 and try out designs in #1. Inventions should be prototypes that are thrown into garbage bin until satisfactory design and code structure, or a better idea, has arrived.
This is by no means easy for most or not time-consuming. So a person must learn to love the processes and intricacies of discovery and invention, in order to put enough effort to improve. If there's resistance to go forward with one approach, one need to invent other approaches that works individually, so that some progress can be maintained. Developers are problem-solvers after all.
Alternatively, there might be other type of work needed to be done that suits the personality better, and where results flow easier.
In comparison, you have a mapping from "I have a problem" to "this type of diagram will help me solve it."
At my first job out of college, my boss was obsessed with diagrams. He made sure that every person on the project could reproduce the system diagram. This means that I was personally given multiple years of instruction on how to visually represent data by someone who was very patiently correcting me. Are you willing to give someone that type of attention?
If you want them to learn the skill in a useful time horizon, and they're willing to improve, you're going to have to practice with them. Pick a thing they know well. Walk through an explanation of the system with them as you diagram it. Then have them draw the system while explaining it and having access to your diagram. Then have them reproduce the diagram without looking at it. This is the beginning - you'll need to do this a lot before they start to internalize a thing you've practiced for years. Over time, you'll realize that you can leave out some of these steps, and over time, they'll have enough bootstrapping that they can produce novel types of diagrams themselves.
It teaches JavaScript, but most mainstream programming languages have the same semantics. It's particularly challenging because building a good mental model of programming takes a lot of time and effort.
In case of simple bug fixes and minor feature addition, my supervisor would be checking everything so I didn't have to worry. For builidng something bigger, no one would be checking everything line by line. I was own my own and afraid to push my code. My team helped me overcome that fear by showing it's okat to make mistakes and nothing happens if you do that. Make mistake, test code, fix bug... it is an iterative process and nothing to worry.
Consider that it might be that your way of drawing diagrams only make sense to you; unless you are able to state clearly what a diagram illustrates, you might just be confusing your colleague by using drawings.
A flowchart sometimes is best, a sequence diagram is sometimes more clear, a step by step list sometimes conveys the work in an approachable way.
The act of writing (and drawing!) acts as a forcing feature for disambiguation and makes us organize our own understanding. I think a diagram that only makes sense to the author is a good first step. Next is going over the diagram with others to see how they interpret it and making changes to make it more universally understandable.
Draw a state machine, send it a few events, let him follow it with his finger. For a state machine, all he needs to do is to keep the last state in his head.
There is a rare case that this doesn't work. But that is not your fault.
I started working on TypeScript Call Graph to see if it's useful -- an experiment of sorts [1]
Could anyone chime in about call graphs and whether they are useful?
[1] https://github.com/whyboris/TypeScript-Call-Graph/pull/1
At any rate I have always struggled to draw or diagram a solution to a problem. I like to write out a paragraph describing it.
I love drawing, but also struggle to make my diagrams relevant and useful in tech applications (software).
On the other hand, diagrams in software have a long and rich tradition. One of the topics I discovered which was fascinating and highly informative was a course on Business Process Management from TU Delft on Edx (though I can't seem to find it now).
I was amazed to discover business concepts diagramed and executable! How's that for formalized.
Besides that, it might just be a case of visual literacy. Katy Borner of Indiana University [3] had a great MOOC, Information Visualization at Edx (though, again, it's not available now).
[1]: https://en.wikipedia.org/wiki/Business_process_management
[2]: http://ebooks.iospress.nl/book/challenging-the-chain-governi...
[1]: https://plantuml.com
Your goal should not be to help him do something that is hard. It should be to understand how to make it easy.
So, perhaps guide him towards the path of least resistance. He is likely not wanting to draw the wrong thing either; tell him to treat the first version as a draft and make him promise he will throw this one away.
Maybe draw something out for him and be willing to make mistakes in front of him, so he doesn’t feel self conscious about getting it perfect on the first shot.
Lower the stakes, focus on smaller problems, and find a shared vulnerability.
Then when things get bigger than a single file/class I introduce the dependency diagram, which helps figure out which components depend on what... This helps you separate concerns logically
Some good tools which help:
When it comes to getting a handle on complexity, I find it better to list all the dimensions of variability and decide how they relate. Any before-and-after (but not necessarily during) invariants are gold. Then I can choose where/when to deal with which dimension(s) while other parts are agnostic to those.
- What did you set out to do?
- What actually happened?
- Knowing what you do now, what would you have done differently?
- How does that generalize to a wider class of situations?
As a programmer also I recommend to learn category theory, which is known for its diagrams (drawing!), its hard for a while, but when you get to adjunctions I found it makes easy to navigate any problem and as a consequence, you can explain/reason about it better.
