Essential Tools for Programmers: An Introduction + Tool #1
The tool that can make or break the aspiring programmer
the purpose of this article series is to steer the aspiring programmer clear from the many snares that await them in the coding wilderness and give them a learning framework that will point them in the right direction from the get-go.
Let’s cut to the chase: the purpose of learning how to program is to develop new — or modify existing — software projects, either as a hobby or for economic reasons. If your reasons are economical (like mine), whether you want to work for a company or launch a business that orients around the software you develop, you need to be able to prove competence. The best way you can prove competence is by creating your own software projects that demonstrate the key skills your employer or client is looking for.
The ‘Essential Tools for Programmers’ article series aims to be a ‘starter kit’ for the aspiring programmer, highlighting the core skills required for learning how to program as soon as possible.
I’ve spent nearly 2 years trying to understand programming — and I still feel I’m barely scratching the surface. I am partly to blame as to why it has taken me a relatively long time to get a hold on the basics — and many may argue that I’m probably not cut out for this line of work if it has taken me this long. However, I largely blame the abundance of ineffective content that the programming world is plagued with. The abundance of information in today’s world is a gift and a curse: a gift because it births new knowledge, perspectives, and opportunities; a curse because much of the information available is useless until it goes through the painstaking process of data handling.
Although the purpose of this article is not to explain why I believe much of the learning material pertaining to programming is really bad — because I will do so in another post — the purpose of this article series is to steer the aspiring programmer clear from the many snares that await them in the coding wilderness and give them a framework that will point them in the right direction from the get-go.
Documentation is the first point of contact we have when learning software. But the truth is, much of the technical documentation that aims to explain software leaves much to be desired. If the majority of software documentation were fit for purpose, the plethora of online programming tutorials would be redundant because documentation is what programming tutorials are based on.
What you’ll find is that many authors of software documentation suffer from the cognitive bias known as the ‘curse of knowledge,’ which is:
“When an individual, who is communicating with other individuals, assumes they have the background knowledge to understand.”
You’ll find this cognitive bias present throughout much of the learning material you’ll come across in the programming world.
However, you still should have the ability to navigate through documentation. By learning how to read documentation, you develop the ability to program on your own accord without being dependent on other people’s thought processes to figure out how to implement a feature or solve a problem when programming. This maturation is essential if you have any hopes of being able to develop software.
When reading through documentation, have a journal handy and summarize what the documentation is trying to communicate. Whatever you don’t understand, write down in no uncertain terms what about it is troubling you. Once you resolve the issue, either by contacting the documentation’s author or through another means, make sure you document and highlight the concept learnt (and share with a programming community!), making it easy for you to reference later when you encounter a problem that is similar to it.
A good book that teaches you how to read effectively is ‘How to Read a Book: The Classic Guide for Intelligent Reading’ by Mortimer J. Adler and Charles Van Doren.
To learn how to read documentation, you should learn how to write good documentation, as you’ll understand the fundamental components that good documentation is comprised of. This will serve as an important criterion: if the documentation you’re reading is well written, yet you don’t understand the contents therein, you have gaps in your knowledge you need to fill; if the documentation is written poorly, then much of your frustration in implementing a particular software is justified and you would be better off looking at the software’s source code instead.
Learning how to write well, in general, will transfer to both writing good documentation and good code. For example, the book ‘Copy Editor’s Handbook (chapter 1 page 3),’ mentions that the desire of the reader, editor, and publisher of a publication is for it to be ‘error-free’ and also proceeds to mention that communication has four constituents: ‘clarity, coherency, consistency, and correctness’ — these constituents apply to both the documentation and the code you write.
Although writing well is beyond the topic of this article, books that look promising in learning how to write good documentation, and technical writing in general, are:
- The Product is Docs by Christopher Gales
- Docs for Developers (APress Publishing)
- The Insider’s Guide to Technical Writing by Krista Van Laan
My educational framework iLearn will teach the art and skill of writing well, among other things. Check it out.
Many developers may consider writing (or reading) documentation a nuisance, but good documentation increases the likelihood of other developers using the software. The same way the quality of a software’s UX (user experience) determines whether users adopt it or not, DX (developer experience) determines whether your product will be used by other developers — and documentation will usually set the tone for the developer on what DX they are likely to experience when interacting with the software.
In closing, I the take-home points for using tool #1:
- Documentation is ubiquitous throughout software development. Learn how to interact with it optimally.
- Focus on those aspects of the documentation that attempt to explain the purpose of the software in principle rather than focusing on the intricate details. By understanding the principal matters, you’ll have a better time unveiling the obscure aspects of the documentation.
- It’s imperative that you formulate and understand the technical terms and concepts of the software documentation you’re learning so that you have a better chance of having a good developer experience.
Thank you for reading!
Be sure to follow the 5d publication and its writers to stay up-to-date!
5d Programming is powered by the Win-Win Economy. Find out how the Win-Win Economy wants to make our economic systems fairer by exploring the links below!
