Rubberduck Developing: Forced Explanation

Being forced to explain your decisions to someone else will be where you get the most value and learning from, not the actual development. If you were to say this to the team a the beginning our response would have been, "What!? No, we are developers and we learn from doing!" Which, to an extent, we still agree with however our documentation forced us to understand. Having to write blogs about our process was a blessing in disguise.

From just developing a feature, you won't fully understand what you've done. You will probably have difficulty implementing it again without referencing your code or articles; nor will you remember the downsides of your implementation as compared to the other solutions you could have chosen. You will forget about the answer to these if you just keep continuing to develop the engine, but forcing yourself to explain what you implemented and why you chose this solution to your past-self, or someone in similar shoes as you, will help you remember your decisions (and if you don't remember you can revisit them).

Although writing for another person, the actual audience of your explanations can just be yourself or your team. Testing documentation is an involved process, one that you won't have time for while developing an engine, but this doesn't mean you can't write as if it were going to be given to someone else. It is similar to API design of an engine, even if you will be the only one using it you want it to be understood by more than just yourself. You won't be able to retain all the decisions you've made when you've finished developing your engine, you documentation will be there to remind you of certain quirks to a feature and assumptions you were making.

Pairing an explanation with diagrams of the problem and videos of before/after will take more time, however you typically will learn something that you didn't discover during development. Each of us on the team had sometime during the semester where we would be explaining what we had done only to realize there was an optimization that could be done, another solution, or even a flaw in our assumptions! While writing about collision solving box collisions, we realized we had made an assumption that all boxes were uniform, this certainly won't be true! We hadn't noticed a problem in testing because we were focusing on getting the different shapes to solve and weren't as concerned with different sizes.

You could argue that it takes time away from learning the next system or growing the engine, but it doesn't. It forces you to slow down and actually digest what you've just done and typically reconsider all the decisions you made along the way. Although this takes more time, it will help you have a better thought through engine, especially if you are developing by yourself, and stop you from having to investigate mysterious bugs because you will know the specific drawbacks of your implementation. The next thing isn't going anywhere, you will only rackup more technical debt by going as fast as you can, especially if there is an assumption in your implementation that you know now but will forget tomorrow.

We feel we must also state there is something magical between the extremes of documentation, With one extreme being where you only develop and don't reflect or explain, this case seems to be easier to fall into but as stated above not as useful for learning. The other extreme is much less common where you only write documentation about engine development without any development, the two pitfalls we see from this are 1) this sounds miserable from a developer perspective and 2) you would be writing from a theoretical stance and the ideal scenario isn't always how things pan out, there are strange bugs that you don't see from just thinking. Pairing application with reflection brings about something unique; do then explain.