Sometime in the last months, I seem to have overcome my long-standing fear of reading another project's documentation in order to understand how it works and solve whatever coding block I'm facing at the moment.

In the past, I would resort to flailing around on search engines or Stack Overflow, hoping that someone would have a simple solution for me to copy and integrate so I could continue on with my "real" work.

"There's probably an elegant answer that someone has already tried to figure out, and I just need to craft the right search query to find it."

I'm often good at finding those, but equally often I tend to do things that nobody would do, and therefore it would stop me. "Why do I have to read all that just to accomplish this little side goal in my project?"

I assumed that because I had no idea where to start, and because documentation is often poorly organized, and because I couldn't search quickly for the answer, I therefore would have to read every single page from beginning to end and hope that it wouldn't be for nothing.

But I've learned from spending time with the excellent, readable, up-to-date, and maintained documentation for Hugo that I can just open a bunch of tabs with potentially relevant sections, skim or read deeply as necessary, and I will often find my answer.

Might not be so easy with projects where the information landscape is more chaotic or cryptic; command-line "man" pages, for example, were maybe good for the era they came from, but still a challenge for me as my expectations are from the current century. But now that my capacity has increased, I might still try anyway.

This seems time-consuming initially, but sifting through those pages frequently is now actually the point for me; that's the skill/rep/practice. It's quite functional to let the docs wash over you multiple times while approaching them with different questions, intentions, or reading speeds:

1. It gives you a sense of the layout of where things are.
2. You're likely to stumble upon things along the way that weren't part of your search but are interesting and might be useful for future possibilities.
3. Over time, you can familiarize yourself with many subconcepts and how they fit into the larger structure.

All this builds strength, confidence, resilience, capacity, and understanding, which pays dividends the more you exercise it.

I used to throw my hands up and say it's a design problem if a beginner doesn't know where to start or can't find the answer quickly. Even if that's true (although I'm not sure whether I believe it now), it's been very rewarding to deal with it anyway.

I feel powerful, as if I can tackle anything. I can get answers by simply reading. I can just look at the code.

I'm no longer afraid to try and understand.

My fear may have also been because it's a challenge for me to focus while reading in general, but that too has gotten better with practice.

It surprises me how this applies to open source code and making sense of it. The first time I saw someone do this was in 2018, sitting beside Émile and watching him casually open the source of Ruby on Rails to understand and then describe to me how some ORM method worked; I never thought to do that in the almost 10–15 years of programming language experience prior, and it still took me some years afterward to try it myself and get over my fear in the process.

Code is also a kind of documentation of how something works, usually messy, but it's also possible to skim through or read deeply to make sense over time—and your capacity increases the more you do it.

So I'm no longer afraid, and it makes "open source" mean something new and powerful to me that, although probably obvious to many people, I perhaps only understood intellectually but never experienced.

Most of my open source contributions have been fixing documentation while trying to understand another project and discovering a 'bug' in the text. That's also worth celebrating, but I'm happy to now feel capable enough to do this with code too; somehow it's possible for me because I started reading the docs.

With my current understanding of the value in documenting things well, I've started doing more in my READMEs, CHANGELOGs, and even higher level in a blog; I do this even if the project is "just for myself" at the moment, because I want to work my empathy muscles and be useful to anyone who may ever try to understand what's going on.

Writing things down is powerful and means that someone else can skip the work you did, so I want to improve documentation wherever I see it.

If I had taken this approach from the start, I'd be levitating right now, so I wish someone had shown me 20 years ago. Maybe it could have happened if someone had guided me or told me I was capable of it. Could I do that for you? Perhaps you can take the chance to practice on something small, and maybe soon enough you too shall levitate.

If you enjoyed that, I also wrote about 'figuring it out much later' with respect to iOS programming and playing the guitar.