There is that workflow where a developer
- meets a problem,
- googles the problem and
- opens links until they find something they can copy-paste to solve the problem.
I'm not the first one to discuss this. The pattern has been identified in the past, and it has been named The Stack Overflow Antipattern. Knowing how to use a search-engine to solve a problem is an essential skill for any knowledge worker in 2022. And despite its name, the Stack Overflow Antipattern is quite powerful. I argue that it will solve a lot of problems developers usually meet. However, there are several disadvantages that come with the workflow:
- Working with a sizable, shared codebase, this workflow most often leads to bad code. The workflow encourages contributors to mix patterns and ignore code that has been written previously.
- This gets especially bad working with opinionated software, e.g., many frameworks.
- In my experience, the more complex the problem is, the smaller the likelihood of finding a solution for the problem is.
- It's pretty hard to actually learn and grow as a developer from copy-pasting answers.
The Setup That Works for Me
In my job as a Data Engineer, I work with high-level languages such as Python, JavaScript and SQL. I do most of my work using powerful libraries and frameworks, currently mostly dbt, django, flask and react. All of these come with fantastic developer documentation. The Python documentation, for example, includes dry documentation of the languages' features. But it also provides tutorials, HOWTOs, as well as guides on how to install, extend or distribute Python modules.
When I have a problem regarding Python, I find reading the Python docs superior compared to the Stack Overflow Workflow. To me, the Python documentation is an immeasurable treasure. When I want to access this treasure, the most obvious way is googling for "documentation python". This leads to docs.python.org. And on that page, there is a search input, which I can use to further navigate. All of this feels slow and is annoying to use when I access the docs 30 times a day. I want an experience with as little lag and nagging with the UI as possible.
Which is why I use Zeal to access developer documentation. Zeal is "A simple offline documentation browser", it's free and open software. I can choose from ~200 docsets, download them to my machine, and search for them without the need of accessing the internet. That last point is especially important to me. Having the documentation on my machine reduces lag as much as possible.
I open Zeal, press Ctrl+k to focus the search bar, type the name of the thing I look for, let's say python:urllib. I then navigate my way to Request Object, using / to open the in-text search. I can manage a couple of tabs if I need to, using Ctrl+t. Zero distraction, one tool for the task. Starting Zeal takes a couple of seconds on my notebook. But once the application runs, I cannot notice the slightest lag when working with it. It's beautiful.
Growing As a Developer from Reading Developer Documentation
So why do I think that reading developer documentation will make people better developers? I believe that official developer documentation is on average better written and has fewer errors than random stuff on the internet. I also believe that good documentation is a reason to choose a framework/software, inversely that it’s a great reason not to use it in the first place.
Let me give an example: When I look up things on the internet, I usually wouldn't search for "How to sort a list of integers in Python". It is more likely that I'd search for something more complex, let's say "How to add Google SSO to Django".
Using Zeal, it takes me a few seconds to search for django:authentication and find a guide on User Authentication in Django. That guide doesn't provide me with code I can copy-paste to add Google SSO to Django. It rather teaches me how user authentication generally works in Django. Reading that guide makes me more knowledgeable about how Django works internally. It also gives me clues for what to search for in the google documentation in the future.
Final Thoughts
While Zeal is a nice open source solution, the docsets it uses are maintained by kapeli, the developer of Dash. Their App for MacOS is really polished and integrates well with Alfred. If you want to support the project, consider buying the software on their website.
Finally, this article is not based on research, but opinion. I want to share what works well for me, and I hope that it helps others improve their workflow and become better at their craft.