Ways to find answers

You start working on a task, you find a library that does everything you need. You start using the library, and then you get an error. You look at the documentation of the library, but it is mum about the issue you are experiencing. Somebody asked the same question on stackoverflow, but no resolution has been posted, yet. If this sounds familiar, that is because it has happened to you at some point (assuming you are a programmer). At this point you can give up, quit your job, move to the countryside or use some of the strategies we cover in this article.

Understanding Documentation

Before giving up hope on documentation let’s look into ways we can study it. Similar to technical books, I like skimming through the whole material quickly. My goal is not to study it, but to get an understanding of the coverage of documentation. Once I know what it covers and to what depth, I can decide which parts are worth for me to invest into. Let’s take a recent example.

One of the tasks on hand I had was to develop a priority queue system for our internal system to replace SQS as a form of communication between services. My first goal was to seek possible solutions that will let us set up a priority queue which is able to handle tasks with arbitrary priority. Candidate tools to help me achieve this were RabbitMQ, ZeroMQ, and Redis. My first goal in skimming through their respective documentations was to seek for any feature that can be used to solve my problem. The documentation will not necessarily use the term you might have in your head, therefore we need to get a general idea of APIs available to us. After quickly going through API documentations, I came to the conclusion that Redis has necessary APIs to achieve my desired result. At that point, I still did not know exactly how to use the APIs, but I knew which ones existed. (Sidenote: The API I ended up using relies on a data model called sorted set, and we can adapt it to our use case.)

Once I settled on the technology, I made a deep dive into the documentation of Redis. Thankfully, it is detailed, with good examples. Did I read all of it? No, I left out parts that are not relevant to my task, such as deployment related aspects of Redis.

One step I omitted in my description of the steps taken so far; Before diving into the documentation, I used a search engine to help me narrow down the list of technologies that can be suitable for my task.

For developers, a more interesting place to search is github, it offers advanced search which can be used to find example use cases of functions, internals of the module we are using or some comments left by the developers. I use this feature often to identify how others have set up their projects, and structured them. Let’s take a look at some of the cases.

Observing others

When we were setting up our front-end application, I wanted to know how to set-up the project properly. One the benefits and drawbacks of the JS development world is that there are hundreds of ways to achieve the same functionality. Once we decided to use Next.js, a framework for developing React applications. We needed to configure it to work with different sets of plug-ins for our front-end application. To see how others have done it, I went to github and search for the following:

filename:next.config.js

The search result shows me all the repositories that have a Next.js configuration. The term “filename” is a keyword for Github’s advanced search functionality. We specify the name of the files we want to search in by appending it to the keyword separated by a colon. In this case, I am not even searching within the file, just searching for the existence of it since all Next.js projects require a next.config.js file.

Our application also uses postcss, so we want to see an example of a configuration with postcss.

filename:next.config.js postcss

Once we update our search term, we get back all next js projects with custom postcss configuration. Neat. You can find a handy page with all the github advanced search features here.

Searching in the darkness

In the previous example, I was looking for examples of projects to learn from them. We can also use the search functionality to find how people use specific functionality of a module you are using. When I was working on a Django project, I had a particularly specific use case for a MultiChoiceField on the seriliaser. I wanted to provide MultiChoiceField choice values from a result of a database query. To see if it is possible to do so, I looked up the official documentation which did not provide a clear answer. Then I went to github and searched for extension:py MultipleChoiceField.

The results showed me different ways people have used the field, and one of the examples I stumbled upon was the same pattern as I was thinking to use. I could have also found out if it is possible by trying it out, but I was lazy and didn’t have the project set-up locally.

The next challenge was coming up with a more advanced use case for the field. We want to have a custom error as part of the serializer error, and the Django Rest Framework (DRF) documentation does have a small section on the feature, but we wanted an error which displayed input and list of choices available to the user. I had an intuition it was possible, since the default error shows the original user input as part of the error message.

This brings me to the next stage of dealing with lack of documentation

All roads lead to the source code.

For a long time, I was irrationally afraid of reading the source of projects. Could be due my previous experience of diving into lasagne code of the Java/Scala world. It can feel daunting sometimes to do, and some projects do not lend themselves for an easy read, but it is worth a shot. I find python and typescript projects source code quite readable. By reading the source code of DRF, we figured out that the serializer use .format on the string with a placeholder of the original user input specified as {input} in the string. By looking at the documentation, we arrive at a nice and concise way to improve our error messages in our serializer.

If none of the strategies above yield a result, you can always ask your colleagues, friends or people on the internet.

I often say, ability to search is one of the best skills I have. My default assumption for any task is always that someone else has already done it. To prove it, I use a mix of terms to use to search on stackoverflow, github or a forum for the project. Only if I don’t find evidence of it, I start considering moving to the countryside.

P.S. Given we are all working remotely right now, moving to the countryside will not help me.