But which manual should I read?

Knowing where to find the answer to your query when you're building stuff for the web can be a sticky wicket. It's one thing to run into an issue while building a website or an app—it’s another thing entirely to do the root cause analysis to find the right documentation, help forum, ancient Stack Exchange/Stack Overflow thread, or random blog that will unlock the solve for you. Memes abound online about senior software devs being "better at Google than you." But really though.

Being a competent web developer (or any sort of technologist for that matter) requires tenacity and refined digital literacy skills to locate answers. You need to become adept at:

• querying both help docs and search engines
• sifting through gobs of documentation at warp speed
• identifying relevant needles in haystacks
• going off trail and trying things on your own when the docs fail you

For many tech issues, it's simply not enough to "Read the Full Manual" or any of the other crass RTFM variants.

As an example, I'm working on a WordPress site with a classic theme with custom blocks, along with a number of plugins to help me build out a custom content model and presentation. The key components are:

• WordPress 6.7.1
• Kadence Theme
• Kadence Blocks Pro
• The Events Calendar
• The Events Calendar Pro
• RankMath for SEO and redirects
• DevKinsta, which runs on Docker

This is not my first WordPress rodeo, and although I'm working with some new tools (i.e., Kadence), the concepts in Kadence are familiar because I've worked so much with Elementor. What's different about this project is the degree of customization and the integration of new toolsets.

Each part of the stack has to work together as a whole, and yet each part has its own idiosyncrasies and issues. Each component has its own opinions and requirements for adding CSS, customizing layouts and templates, and doing any other modifications. Things that seem like they should be built-in features with backend controls require overwriting PHP templates and really digging into the browser's Inspect tool to understand the CSS structure for proper targeting.

Locating the right manual

On the surface, it seems simple: questions about Kadence should have answers in Kadence docs; questions about WordPress should be in the WordPress docs, questions about The Events Calendar should have answers in The Events Calendar docs, etc. But it's more complicated than that. Sometimes the question is tied to something I want to achieve in Kadence, but the real answer is in the WordPress.org docs. Or maybe I want to do something specific with customizing CSS in The Events Calendar, which then requires a trip to the Mozilla Developer Network docs or W3Schools. And plus, I've encountered scenarios where documentation is sparse, outdated, or sometimes nonexistent. Those are situations that require you to "move fast and break things" until you figure out what works.

And then sometimes there is good documentation, but you have to cross reference like three different parts of the manual to make sense of what it takes to achieve what you want, but then, by the time you piece everything together, you've almost lost a grip on your original goal because reading the manual brought up several other important points that also have a bearing on the project.

Early on in the build, I created a list of helpful help docs while I was searching and reading the documentation. My list quickly grew to nearly 30 articles. I even recorded a Loom video to myself explaining some of my customizations because it took so much spelunking in the docs and the code to build the solution I wanted.

Good docs are only part of the battle

And that's the other thing about reading documentation: It can tell you what to do and how, but it can't help you with the why. That's something you need to know before you go to the docs. For every article I read (skimmed) and every link I saved in my own curated list, I knew why I was searching. I had a relatively concrete vision, and I was simply looking for the what and the how. That's what docs do best.

It also helps to have a basic understanding of the history of the tech you're using. I have a good grasp on the broad structural differences between classic themes and the more modern block themes, the Gutenberg editor, template overrides, adding code to functions.php, and a variety of other general conceptual need-to-know things when it comes to working with WordPress. That's a function of knowledge built up over time and experience of working with the tool, and it certainly animates and focuses my time reading docs.

Since I know some of the what and how of WordPress in general, it makes it easier for me to understand how the help docs from other tools relate to the overall project. I want to use each tool (Kadence, The Events Calendar, etc.) effectively and efficiently, and I want them to work together harmoniously. That's a tall order for different plugins and tools that have their own opinions of how things ought to be done and different affordances for accomplishing those things.

Hence the need for good docs and reading those docs. My current project has certainly given me more empathy for both the newcomers to the field and for the technical writers who write up how to's and dev docs.

For the newcomers, there's a steep learning curve that can be traversed only through time and persistence. I've had the wonderful experience of reading and understanding docs that four years ago would have glazed my eyes over. I've kept reading and looking at code samples, even if they were unintelligible to me. That's how kids learn their alphabet.

For the docs writers, there's always more to be documented. There's always a fringe use case, a question that a user has that doesn't have an answer written down just yet. Writing good documentation is a lot of work, and it's definitely an act of caring for the user. I respect companies that invest appropriately in documentation because it shows that they actually care about customers.

And as to the question, "Which manual should I read?" the answer is always: "As many as it takes to find the answer."