CohortCode

Typing the Docs 2021-01-26 06:36:51

When you don't know how to make something work in code, the old time suggestion was to RTFM. It meant read the fucking manual.

Of course, back in the RTFM days, you wouldn't ask somebody how to do something unless you were into it. And, if you were "into it" you'd be expected to put in the effort to learn. It's a lot of work to study Mandarin Chinese or Arabic or other script language. It's a lot of work to remember calls that work in the programming language. It's similar when trying to learn any abstract, translatable concept. You need a mental map to remember how this equates to that.

When I want to learn more code, I might take the time to type out the documentation of some functionality I want to remember. If I were to create my own code, I'd be expected to create documentation for others. In this vein, it makes sense that I should I practice reading documentation in addition to writing code.

When you type in the docs, you are required to slow down and understand the choices the writer made. Where do they put the square brackets? What are the short-codes you need to understand to decipher the instructions? What terminology or jargon will you need to learn to connect the dots?

If you want to learn anything, whether it be how to write literature or write code, typing in the words written by somebody else provides a chance for your brain to wire up and make the connections that lead to memory and learning.

Brian Ball

The Concept Wrap your code

More from CohortCode

Documentation Driven Development is a thing that I've recently read about. I really like it for developer facing code -- like libraries/packages/frameworks -- because the documentation is the UX surface area for such. So instead of making it an afterthought, you really figure out how the user -- in this case developer -- is going to be interfacing with your code and you let that drive the design of the code.

I think a masterclass in good documentation is the Laravel docs. I think what makes it so good is scope coverage. Its docs begin not with details and descriptions of what the Framework looks like, but rather the philosophy of why it works and who it's for along with a high level conceptual overview that a non developer would even be able to grasp.

This broadly scoped portion is partitioned well from the brass tacks portion where a developer refers to when they forgot how to associate two models in many-to-many relationship. I've done this so many times by the way.

Stripe is another example of great docs. What I found while researching them is that great API coupled with great documentation can be a competitive core competency for a technology product.
2021-01-26 10:38:07