March 02, 2021
In the process of learning Go language programming I have consumed a lot of written and visual material. Today I listened to a few minutes of the Go Time podcast, where they were talking about documentation. The introduction to the episode really resonated with me, and so I wanted to capture it in my words here.
When first starting a new topic, particularly a technical one like, say Go programming, tutorials are a common starting point. Explanation mixed with samples, something you can follow along with at home. Learning my mimicking.
How to resources are aimed at solving a particular problem. How to I set up an HTTP router in Go?, or How should a go project be structured? A how to is more narrowly focused. It aims to impart knowledge about this one specific topic.
Somewhat broader in scope than a how to, an article or presentation (i.e., at a conference) dive a bit deeper into a topic. It isn’t a tutorial, assumptions are usually made about what you already know. And it isn’t a focused as a how to. It adds some though process to the solution or technique discussed.
Documentation is a dictionary. An reference. You are looking up the specifics of an API or library. Depending on the maturity of the documentation, and whether it includes examples or not, finding information in the documentation can be difficult. If you know the package or library you need and only need to refresh your understanding of it’s parameters and return value, documentation is fantastic. If you are unsure, and are hunting for the right tool, documentation can be frustrating.
In the course of learning a new programming language, I move through all of these categories of documentation. While working through a tutorial I may digress into a how to or look up things in the documentation. Generally though, I move from tutorials through how to and articles, and finally to documentation.