Code, Leadership & the Remote Dev Life

Tag: WordPress Plugins

  • How to Onboard a New Developer to Your Plugin Codebase

    How to Onboard a New Developer to Your Plugin Codebase

    Bringing a new developer into your plugin project can go one of two ways: smooth and productive—or completely chaotic.

    I’ve seen both.

    Whether you’re working on a public WordPress plugin or a custom solution for a client, onboarding a new dev isn’t just about giving them access to the repo and saying “good luck.” It’s about giving them clarity, confidence, and context.

    Here’s how I do it now—and what I wish I had done sooner.

    1. Set the Stage: Explain the Plugin’s Purpose

    Before diving into any code, I always walk through why the plugin exists. What problem does it solve? Who are the users? What’s the long-term goal?

    Too often, devs are thrown into a project and only understand the what, not the why. That leads to narrow thinking and missed opportunities for improvement.

    Even a short video or a quick explainer document helps give a mental model of the plugin’s architecture and intent.

    2. Provide a Dev-Ready Environment

    Don’t make new devs spend hours figuring out how to spin up the environment.

    If you’re using Docker, share the commands and prebuilt configs. If you’re on a local dev tool like Local or Lando, make sure setup steps are documented. Add a README.md with installation steps that actually work.

    The faster a new dev gets to running code, the sooner they start contributing.

    3. Map Out the Architecture

    Your plugin probably has its own structure—maybe includes/, assets/, templates/, etc.

    I usually include a brief “file structure” doc with one-liners explaining what lives where. Example:

    /includes/classes/ → main plugin logic  
/includes/hooks/ → custom hooks and filters  
/templates/ → frontend output

    It’s basic, but it orients people quickly.

    Bonus points if you document how custom post types, taxonomies, or meta fields are registered and used.

    4. Document Common Workflows

    Are there scripts for releasing new versions? Conventions for submitting PRs? Gotchas when building new features?

    If you’ve been working solo, you’ve probably internalized all this. But to a new dev, it’s tribal (yes tribal, not trivial) knowledge.

    I keep a CONTRIBUTING.md file with:

    • Branching strategy
    • PR review process
    • Linting rules
    • Deployment steps

    Even if you’re not running a large team, this makes life easier for you and your new dev.

    5. Pair on One Task

    After the walkthrough and docs, I always sit down (virtually or in person, I mostly do it virtually using Google Meet, Zoom or a similar service) and pair on a small task. Nothing huge—maybe a bug fix or a tiny feature tweak.

    It’s not about the code. It’s about watching how they approach things, answering questions in real-time, and catching any disconnects before they grow.

    That one session can shortcut days of confusion.

    6. Encourage Questions (and Capture the Good Ones)

    New developers ask great questions—ones you’ve stopped thinking about long ago. Instead of brushing them off, I treat them like gold.

    If they ask something insightful, I update the docs. That way, every new hire makes the process better for the next.

    7. Give Them Ownership Early

    Once the new dev is up to speed, I assign something meaningful. Not just small bugs, but a feature or enhancement where they can leave their mark.

    That sense of ownership builds momentum. And nothing motivates like being trusted.

    Final Thought: Onboarding Is an Ongoing Investment

    Yes, it takes time. But good onboarding pays dividends. Developers become confident contributors instead of code tourists. They build faster, break less, and stay longer.

    Treat onboarding like part of your dev workflow—not a one-time checklist. Your future self (and your team) will thank you.

  • The Hidden Costs of Not Documenting Your Plugin Code

    The Hidden Costs of Not Documenting Your Plugin Code

    We’ve all done it. You’re deep in the flow, building out a plugin feature, squashing bugs, hitting milestones—and you think, “I’ll document this later.”

    Then later becomes never.

    I used to think documentation was a “nice-to-have.” Something you do when the real work is done. But over the years—especially maintaining my own WordPress plugins and client custom solutions—I’ve seen how the lack of documentation creates invisible (but very real) costs.

    Cost #1: Slower Development (Yes, Even for You)

    The biggest lie we tell ourselves is that we’ll remember how something works “because we wrote it.” Six months later, you’re staring at your own code like it’s a riddle written by someone else. Without inline comments or clear README notes, every revisit becomes archaeology.

    Worse, even current development slows down when you forget why a helper function behaves a certain way, or what parameters that hook expects.

    Documentation isn’t for “someone else.” It’s for future you.

    Cost #2: Onboarding Hell

    Whether you’re growing a team or just collaborating with another dev for a sprint, a lack of documentation turns simple onboarding into a game of 20 Questions. What does this function do? Is this filter still used? Why is this action hook conditional?

    Every minute your teammate spends asking basic questions (or worse—debugging things they don’t understand) is a minute lost to productivity. Multiply that over weeks or months and the time cost is huge.

    I’ve had clients switch agencies purely because “the last dev left and no one knows how their plugin works.” That’s not a tech debt issue—that’s a business loss.

    Cost #3: Increased Bugs and Regressions

    When you don’t document intent, you leave interpretation up to the next developer’s guesswork. And guesses lead to bugs.

    I once refactored an old plugin and removed what I thought was redundant logic. Turns out it was a workaround for a very specific WishList Member bug that I myself fixed from 5 years ago. That workaround wasn’t documented anywhere—only realized the issue after customers started reporting it in support.

    One comment or note would’ve saved hours of debugging.

    Cost #4: Lower Plugin Adoption and Community Contribution

    This one’s especially true for public plugins. If people can’t figure out how to use your plugin or contribute to it because there’s no clear documentation, they’ll move on to one that is documented—even if it’s less powerful.

    I’ve seen talented devs build incredible tools, only to wonder why no one uses them. The code may be clean, but if the onboarding experience is confusing, your plugin will sit idle.

    Documentation isn’t marketing, but it is user experience.

    Cost #5: Burnout

    This one’s more subtle.

    When you’re the only person who understands the plugin codebase, everything lands on your plate. Every question, every issue, every tweak. You can’t delegate, you can’t scale, and eventually… you get tired.

    I’ve burned out maintaining side projects because no one else could help, and the idea of “explaining everything” felt more exhausting than just doing the work myself. That’s a trap.

    Good documentation is how you offload that burden. It’s how you give yourself permission to rest and step away when needed.

    So Why Don’t We Document?

    Honestly? It’s not sexy. You don’t get dopamine hits from writing function descriptions. There’s no client applause for a well-written README.

    But over time, I’ve found a quiet pride in it. When a junior dev says, “I figured it out from your comments,” or when I revisit old code and don’t feel lost—it feels damn good.

    How I Approach Documentation Now

    Nothing fancy. Just consistent:

    • Inline comments for logic that’s not immediately obvious
    • DocBlocks for all public functions and hooks
    • README.md files that explain the plugin’s purpose, how to install, how to use, and how to contribute

    When I’m pressed for time, I at least leave TODO comments or open a Notion page to circle back.

    The key is to treat documentation like part of the code—not an afterthought. Just like you wouldn’t commit broken syntax, don’t leave logic undocumented.

    Final Thought

    Code is temporary. Even plugins you’ve maintained for years will eventually evolve, be handed off, or sunset. But documentation is what gives that code clarity, life, and continuity.

    If you’re not documenting your plugin code, you’re silently agreeing to future confusion, wasted time, and limited collaboration.

    It’s not about perfection. It’s about leaving breadcrumbs—so someone else (or future you) doesn’t get lost.

    Write the damn docs.