Thanks to our community sponsor
Creating support, feedback channels and documentation for developers is a critical piece to the puzzle. Allen Smith has taken the role of Developer Advocate at WooCommerce with drive to bring the best to the fingertips of the dev community. His global experience in platforms and community bring a fresh vision into the space and we get a chance to learn more about Allen and how he is seriously doing the Woo.
A Chat with Allen
In episode 75, Brad and I chat with Allen about:
- What the developer advocate for WooCommerce does
- The developer resources for WooCommerce and how they are taking shape
- How Allen comes from a diverse background of communities and languages with a fresh perspective on Woo
- The bigger picture of documentation around the WooCommerce developer community
- The challenges and solutions for keeping documentation up to date
- Where Allen is finding success in creating and managing feedback channels for the developers
- What options there are for jumping into the Woo developer community at WooCommerce
Connect with Allen
Yes, this is the transcript. But not in the traditional sense, transcribed word for word. We do not speak as we write. Often the flow of transcribed content is hard to follow. So I have taken it a few steps further by seriously editing, at times, the conversation and even using my editorial freedom to clarify some points. So enjoy.
Brad: Welcome back to another exciting episode of Do the Woo. I'm one of your hosts, Brad, and I'm here with BobWP. Bob, what's happening?
Bob: What is happening? Just a lot on the plate and keeping busy. So nothing really new, but new in a sense...
Brad: Nothing new, Bob? Come on, you're being modest.
Bob: Nothing new with having stuff on the plate.
Brad: You could just rebrand and launch a whole new website. No big deal.
Bob: Ha. Doing good.
Brad: I know you've talked about it. We're going to have some deeper conversations, but DoTheWoo.io is live now, right?
Bob: Right, right. We are good to go after all this time. I pushed the button. It's live. Well, I didn't push a button ... that sounds too easy.
Brad: I'm going to need you to push the button. Somebody somewhere pushed a button and its live. So go check it out. DoTheWoo.io for all things Woo. If you're a builder, specifically, developers, designers, entrepreneurs, building stores, supporting a store, this is the resource for you or one of the resources because it's a great segue into our guests today.
But right before I do that, I do want to give a big shout out to a href="https://woocommerce.com/" target="_blank" rel="noreferrer noopener" aria-label="WooCommerce.com (opens in a new tab)">WooCommerce, as always, our community sponsor. If you're not familiar, I would probably ask why you're listening to this podcast. Maybe you're just wondering what it is. So WooCommerce is really the leading plugin specifically for WordPress, to power your e-Commerce store. It has a ton of functionality. That's what we talk about each and every week on this show and have various guests on.
This week, we're focusing on the developer side, which is really a direct relation to what you just launched here, Bob, and the changes with the podcast and with the content. This week, we've brought on Mr. Allen Smith. So welcome to the show, Allen.
Allen: Thank you so much. Thanks for having me.
Brad: I've teased it up in terms of WooCommerce development, but why don't you tell everybody? What is your official role within WooCommerce and how does that tie into the developer side of it?
Allen Smith, Developer Advocate at WooCommerce
Allen: Yeah, absolutely. I am a developer advocate for WooCommerce here at Automattic. My job is to make sure that the developer experience for people who are building with WooCommerce, be they builders, people who orchestrate by putting those together or people who build extensions that build on top of WooCommerce, it's my job to make sure that their developer experience is both delightful and that they have the things that they need to build the things that they're trying to build, to solve the problems that they're trying to solve for merchants.
Brad: Yeah. I love it. I've written a number of books on WordPress development on the more technical side of working with WordPress for developers, designers, and basically people building sites with WordPress. One of the things I really stand behind is that if a platform is hard to work on, if you can't get the buy-in from developers, it's going to be much harder to get the users because ultimately, we're the advocates for the platform by and large. Not saying everybody using WordPress is a developer or has to be a developer. They certainly don't.
But if the developers are really backing the platform, they're going to do a lot of the promotion. They're going to be the advocates, either directly or indirectly, just by using the platform. So having somebody in your role and really helping curate the knowledge, the discussions, the support on a platform as advanced, if you will, as WooCommerce, it has a lot of moving parts and a lot of things that you can do with it, I think is hugely important for any platform.
So I'm really glad to see a more formal structure around this than what we have seen in the past, where it was more just community-based. In the WordPress world we had the codex and it was like, "Well, it's kind of there, but I don't trust it." So it feels more mature, I guess, is the point I'm trying to make, which I think should give developers that aren't, or that are new to this space, or that are maybe thinking about jumping into WordPress and/or WooCommerce, more confidence to say, "Hey, there's actually a lot of support here for me as a developer, not just as a user, but as a developer. There's these tools. There's resources I need to learn and to grow, to be confident in this platform."
What are you hearing? Are you getting some of the same feedback? Are you really seeing people take hold of the information that you're putting out there, or what's your take?
Developer resource portal
Allen: Yeah, absolutely. That's one thing I noticed as soon as I started. There is so much that's out there already. A lot of the feedback we were at least initially getting from developers was that there were good resources, but so much stuff was really hard because it was spread out. So one of the things we did initially was we created a developer portal that aggregated all of those resources in one place. Now if people go to developer.woocommerce.com, they can just see a list of everything from reference docs to guides, examples. There's links to all of the libraries that people might want to use.
Bob: So as I understand, that you were not necessarily deep in WooCommerce or WordPress prior to coming to WooCommerce. I like to hear a little bit about the journey. What were you doing before you entered the zone of WooCommerce?
Did Allen Do the Woo before coming to WooCommerce?
Allen: You're right. Yeah, I'm not a PHP developer. I'm not a WordPress person. I was not a WooCommerce person prior to joining the company. So I was honestly a little surprised that I got the interview for the job. But before this, I had been working in pretty much just about every other language. I worked at GitHub for several years before this. I started there as a trainer, and we would go out to companies and we would teach people how to use Git and how to improve their development workflows, using Git and GitHub.
Because of that, we had to learn a lot of different workflow patterns. We had to learn a lot of different programming languages and frameworks and all sorts of things. So for me, it very much set the stage in learning how to bridge the gaps between all of these different communities. After I started at WooCommerce, it was then that I learned that this was something that was very important to them and was finding a way to bridge the gaps between these divergent communities that they were going to have to bring together.
Difference communities and languages
So we have the react developers who know all about the front end stuff, the very modern way of doing these single page apps that have build systems and all sorts of things that WordPress and WooCommerce had never historically relied upon. Then you have these veteran PHP developers who know the framework, know the platform inside and out, and how to find a way to help these two groups help each other build really, really cool things for merchants.
So my background prior to WooCommerce really came into play there because I had worked in all of these different communities and all of these different languages, and finding a way to help these groups communicate and find the commonalities between them, I think, is something that was very important to them.
A fresh set of eyes (and ears)
Brad: It sounds like bringing you in without having some of that direct experience in those areas that you mentioned, probably really set this up for success, this roll up for success, because you're coming in with somewhat with fresh eyes, right? Like you said, you weren't in those communities. You weren't diving in head first into PHP or even WooCommerce or React. So coming in with fresh eyes, I think, is probably a smarter approach versus somebody that's been at the start or even just more familiar with WooCommerce and where we're at, because you can really take a step back objectively.
Like you just said, "Here's the bridge we have to gap. How do we do that?" versus saying, "Well, I've been doing this since it started seven or eight years ago. I know what we're going to do." You know what I mean? So I think having those fresh set eyes was really sets this role up for success in what you're doing as a developer advocacy in a positive way.
Allen: I totally agree. I think that when you have diverse opinions, diverse viewpoints, trying to solve problems, it helps everybody see their blind spots. That's been my experience coming into the WooCommerce community, into the WordPress community, and then by extension, the PHP community as well, is they're just like a lot of these other communities, in that they have solved the same problems the same way for years and years and years. So when you start looking at the same problem in a different way, you can approach it in a novel way.
So I'll give you an example. When I started, one of the questions I had for our development team was, "Okay, how do we go about setting up and managing a development environment for WooCommerce?" There's not a great definitive answer because there are tons of different ways that you can do it. Some people use this tool called Champ. Some people use VVV as a tool for managing these Vagrant installations.
Then there's another tool called WPN, basically, it runs on Docker and things like that. So we got to explore all these different ways to create and manage these environments to find a way that works really well for people.
Brad: Yeah. It's a good example, because again, lowering the barrier to entry for developers is ultimately going to make it a little less scary, less intimidating, and maybe even more inviting in a sense of saying, "Oh, I am familiar with a VVV approach or a Docker approach or whatever they might be familiar with and say, "Oh, they have guides to walk me through this or steps that I can get this set up."
Next thing you know, you're running it and then you're starting to get excited. Like, "All right, well that works. Now let me start peeking out under the hood a little bit, using some of the docs." So maybe we can dive into that a little bit more and, and talk about some of the ways that you are approaching developer advocacy, some of the different tools that are available either online or maybe in other areas. But we can talk about those different resources that people can look for.
The docs and resources for developers
Allen: Yeah, totally. What we've had to do, because we noticed there's a lot of potential here because for better or for worse, some of the things that we have out there are a little bit out of date. Then there are a lot of things that just don't exist altogether. So what we had to do when I first started, was we went through and we did just an audit of all of the developer-related content that we had. We identified for some of those gaps were. Also reached out to the community to see what would be most valuable to them.
Overwhelmingly, two things stood out from the developer community is that they want thorough documentation of the code itself. They want clear technical guidance in terms of how to go about various things on the platforms. How do I extend the shopping cart? How do I hook into the checkout flow, for instance. Things like that. They want very concise guidance around these things. So these are the pieces that we're focusing on right now.
The developer portal that I mentioned a little while ago was very much about solving that discoverability problem that we had, which was that we have all these resources, but nobody really knows how to find them. It's pretty much a tribal knowledge thing. Now, this next phase where we're creating the new content is focusing on that technical guidance that we can provide, so that they're using the best practices for developing for the platform, be it adhering to certain linting guidelines and documentation standards, to make sure that they're developing against the platform in a way that is ... maybe we could call it future-proof, so that they're not going to have their extensions stomped out when the platform changes.
Thirdly, to make sure that the work that developers are doing is constantly providing that first-class experience to merchants. So as you all know, as WordPress developers, because there are so many different ways to do things in WordPress, it's very easy to let that extensibility turn into hacked-around things that look like they're pieced together. That's an unfortunate side effect of that balance between extensibility versus standardization. So what we're trying to do is we're trying to respect that extensibility in a way that still provides that seamless customer experience and merchant experience.
Brad: Yeah, that's actually a really good point because it reminds me of, in a more extreme example, page builders and site builders, where we are giving everybody tools, the average user tools to customize anything on the look and feel and layout is great, until it's not great. Then the entire net starts looking on like MySpace pages and years ago, right? It's just, "Cool, you can change everything, but should you give that power to every user on the site?
Maybe just keep it so a couple of core users have that knowledge. But that's a more extreme example of what you're getting at, but at the end of the day, you're right, because if WooCommerce, the experience that someone puts together builds ... Whoever's using that platform from a store owner standpoint, that's their impression of WooCommerce. It's not hosted in the sense of Shopify, where these really tight guard rails that can prevent bad things from happening.
But that's the give and take of extending the platform and having that flexibility just like WordPress. It's the same thing, right? If WordPress across the board looks terrible on every site that you visit that is WordPress, your assumption is going to be, "Oh, WordPress just looks ugly and it's terrible." It really has nothing to do with the platform. It's just the fact that everybody made it look bad or made it very shaky or clunky or whatever. So that's a fair point.
I'm curious. Once you did an audit of everything, and there's a lot. Like you said, it was all over the place. Some of it was probably official. Some of it probably wasn't. It was just all over the internet. Now that you've gotten things back in a better spot ... and I love developer.woocommerce.com. It's just a nice layout and a great site because you can easily get to what you're looking for. Reference docs, libraries, guides, examples, tools. Just quick and easy. These are the things I'm looking for as a developer.
Keeping the docs updated
I'm curious what you do because being open source and the nature of open source and it moves quickly and WooCommerce moves very quickly. There's a lot of releases, more so than WordPress in terms of major releases. How do you keep this updated? How do you keep it current? How do we know when we're looking at some of this information, that it is the most current? It's not something that was written a couple of years ago and just hasn't been updated, because that's been a challenge for WordPress since the beginning.
Allen: It's a huge challenge. To be quite honest, a lot of the stuff that's linked on there is probably outdated. So we have guides for putting together extensions and themes. I know that specifically, the themes guide, I think, was written in 2017. These are those pieces that we need to go in and update at this point, so that we make sure that they are current. So that's one challenge that we're facing.
Some of the other things that we are doing right now is for instance, our reference docs have been recently updated. So if you go to the WooCommerce core, it's the core code reference basically. That entire site has been redesigned. What we do now is we generate that static site using the inline documentation that's alongside the code. So if code gets built, it generates those docs. So any changes to the code will be automatically reflected in the documentation.
Brad: I love that. Yeah, it's awesome.
Allen: This was a problem we had previously because we were using a deprecated library for generating those docs. What ended up happening, I think, is we stopped generating the documentation. So the platform kept getting developed upon, but the documentation lagged behind quite a bit. That, I think, is not an issue anymore.
Brad: Yeah, that's great. I think any developer out there knows the struggle of documentation, working on WordPress or not. It's the thankless job. It's there for the developer. The end-user's never going to see it or care about it. But, man, as a developer, we care about it. Whether it's us reading our own code a couple of years later, or digging into somebody else's code, that stuff is hugely valuable. I think it uses the DocBlock standard, right? PHP DocBlock. I'm assuming it's the same as WordPress, which uses DocBlock.
Allen: I don't know if we use DocBlock or not. I think it's PHP Doc 3, I think that is what they switched too.
Brad: Those are so cool. So no matter what you're building, you can look at this standardized way of commenting and documenting your code, and then you can auto-generate docs for it. Like you said, at the very least, reference docs are exactly what's in the code. It just cleans it up in easier format to read on a website, which is awesome because it does take that away. That's the problem that the codex had for a long, long time before developer.wordpress.com started doing the same thing. A lot of good information, but it was just constantly out of date.
Wouldn't tell you if something was deprecated until you went to use it. then you're like, "Oh, yeah, this is deprecated. I shouldn't be using this." So it's a challenge, but it looks like you're keeping up on it, which is great.
Allen: It's really great, too. Maybe I'm just biased because I've working to get it out, but if you generate your docs, you can store them in your repository, alongside your code and GitHub will automatically build that as a doc site and host it on GitHub for you. So you have your code and your documentation living side-by-side. You don't even have to worry about deploying it, manage your docs in WordPress or something like that. You don't have to worry about that because GitHub can serve it for you where the developers are, which I think is really cool.
Brad: That is cool. I write books, which are again, open source, the challenge is keeping things updated. So people ask, "Well, isn't this out of date really quickly?" By and large, the answer is no. It might mean newer things have come , but we discuss and write about everything in a way, like you said, that is backwards compatible.
If you use the proper APIs, if you use a proper class of methods and everything, and you do things the WordPress way, it should always work. It's just a matter of if newer features are available or not, or something becomes deprecated. But what we like to teach and what I think is just people getting more comfortable going under the hood because at the end of the day, the code is your greatest tool.
When you can really understand how to dig into the core of WooCommerce or WordPress or some other plugin you're looking to extend and understand what you're working with, that's the greatest tool in the world because all of your answers are right there. It's just understanding how to find them and how to read them and understanding of how the docket, the commenting system works and all that stuff. But once you get a decent grasp of that, then many times you can just go right into the code and get the answers that you need. You don't have to rely necessarily on, "Is this codex out of date or is this tutorial from a couple of years ago still accurate?"
Check the code. The code will tell you if it's accurate or not. So again, it's that, making sure people understand that it's okay to look at code and the core. Just don't touch it, but you can look at it.
Allen: That's been our experience, too, in talking to developers, especially in this community. People who are trying to solve specific problems, tend to follow a very determined journey, regardless of what they're doing. They'll start by looking for some high level guidance documentation. How do I extend X? If they can't find it there, then they start looking at the documentation that's been generated about the API itself. If they can't find it there, then they dive into the code and they figured out on their own.
I think that this is really interesting in the WordPress community specifically because unlike other platforms, since the ecosystem of developers is much more interdependent than you would see on other platforms. So you have to understand how to navigate not only your code and the code for the core platform itself, but also the code of all of the maybe sibling plugins that you may encounter. So it's helpful to have those skills of navigating the code in some standardized way.
Bob: Yeah. I can certainly relate. I've been taking a extended break. In fact, it's longterm when it comes to writing tutorials on WooCommerce extensions on my site and just keeping those up. So as a result, the doctor was able to take me off my meds, and life is much better now that I'm not writing those. But seriously it is. Documentation is a challenge. You had mentioned speaking with your developers, the communication you're having with them.
Managing and creating those feedback channels
I know, again, with documentation, you're getting the feedback and those channels in place, and that can be a challenge. Making them centralized, where they're not going off in all different directions. What has been your experience and what are you doing with that feedback channel?
Allen: Yeah. So we're doing a couple of different things. In the past, what we have done is we had a monthly community chat that happens in Slack. My colleague, Jonathan, who's our community manager, he's done a great job of putting this together and managing it. Then I took over when I got more acclimated to my role. So we're doing that once a month. That's been a great tool for what you might say, bi-directional communication, mostly outward communication to developers, a little bit of feedback coming in.
What we wanted to do is increase that multi-directional conversation between developers that may or may not involve us. We want to be involved in that, but we definitely want developers who are working with the platform to chat with each other as well. So we started setting up weekly office hours where developers can share their challenges and their expertise with each other. They can up-skill if they want to. This is not us teaching people how to do things. This is developers organically helping each other.
If somebody has a problem, there's a developer over here who has 15 years of experience who has run into this problem in WordPress or WooCommerce before, and they can help. That helps people build each other up. That's one thing that we've been doing.
Internally, what I've been doing is I've been working with three separate teams, specifically three separate engineering teams. We have our core WooCommerce team. We have a team who manages the WooCommerce admin extension. So all of that react framework stuff that we do. Also we have a team who is responsible for managing WooCommerce Gutenberg blocks.
So I've been working directly with these teams once a month, to coordinate around issues that are affecting multiple extensions, things like that. I'm also working with our support team to identify specific issues that merchants themselves are running into, to make sure that those issues can get the attention from the engineering teams that they need in order to be resolved quickly and with the right priority.
Brad: Yeah. I love the office hours, the developers getting together and just helping each other. I think just the nature of open source, that's in all of our DNA. I think it's one of the reasons we're drawn to open sources is that community, "Let's help each other learn and grow."
I remember seeing that early on, in the old IRC days within WordPress, where many of us, back when I got started, it was just a bunch of us figuring things out together and just helping each other and to see it be more focused out where it's not just WordPress. It's like, "Okay, let's talk about one specific tool within WordPress. Would this be in WooCommerce?" But the idea that people want to help each other and share experiences because it's a good feeling.
If I can answer a question that I went through at some point and figured it out and point you in the right direction, I'm going to feel good about that. Likewise, if I have a question and you help me, we're all going to feel good about helping each other out. So I love that idea because it's fun to share experiences, share challenges. We've all done a number of different things. Like you said, there's a million ways to skin a cat or whatever, just understand the nuances of challenges and problems. Just getting stuff out in the open can help you figure out a solution. So I think that's a really cool thing that you all are doing.
Allen: Yeah, totally. I can't take any credit for it because really it's something that was already happening. This is one of the nice things about coming into a community that is already so thriving is that this is something that was happening 24/7 as it was. What we did is we just added a little bit of structure in when it happens, and the developers are taking care of the rest of it.
Brad: Very cool. Obviously, WordPress is all about contributing. WooCommerce is all about contributing. How can people get involved and help with this and help you? Are there opportunities that people can contribute to different forms of documentation or discussions? We talk about the feedback and things like that, but are there other areas people could jump into to help?
Jumping in to help the Woo community
Allen: Yeah, absolutely. I think the easiest way for people to jump in and help right now is to attend one of these office hours sessions. Even if you can't make the office hour session itself, we tried to pick a time that would let as many overlapping time zones participate as possible. But right now there's just one session. So that unfortunately leaves basically half the globe in the dark literally, trying to participate in these.
If you're not able to, I still encourage people to join our Slack community. You can do that by visiting the developer portal at developer.woocommerce.com. There's a link where you can get signed up to our Slack community, and you'll be added to all the channels where we discuss troubleshooting. We discuss development issues. I know that specifically in our developers channel, we have builders and we have extension developers who act with each other and share tips and tricks and all sorts of stories from building things and solutions. That has been really great.
If people want to contribute to core projects, a lot of our projects are open source. We do maintain some things privately, but the majority of what we have out there is open source. We have a system of labels and a lot of our repositories for things that would be a good first issue if somebody wants to contribute in that way. So I'd encourage people to take a look at those issues in the WooCommerce repository specifically.
Brad: Yeah. I always recommend if you're really wanting to up your game quickly and really just get familiar with WordPress, WooCommerce platforms that maybe you're not as familiar with, the best way is to jump into some of these things. Even just the conversations and start asking for help. I learned really how to build dynamic websites through forums 20 years ago and just asking a lot of questions.
Over time, I went from asking questions to answering a lot of questions and that's the natural flow here, is you'll go from looking up questions, trying to get answers either through online or in Slack or wherever, to helping people answer questions that they're stuck on. You'll see that progression very quickly. So dive in and help out. There's so many opportunities to help, even if it's contributing to documentation, which again is such an important, critical component of any software development. But it's just one of those under the hood things that a lot of people don't think about, but we as developers know how important it is.
So that's an easy way that you can get involved, even if you don't know all the ins and outs of WooCommerce across the board. You can help out with some of that as well. So a lot of great resources over at developer.woocommerce.com.
Beta testers from all levels are invited
Allen: I was going to say one other thing that people can do, especially if they're not developers or if they're not code savvy, we're always looking for beta testers for new versions of WooCommerce, new versions of packages that come out. So if you think of WooCommerce admin, or I think there was a new navigation package that we were beta testing a few months ago. We post those releases on our developer blog and people can get involved by helping us test out these new extensions before they land in core.
That's one thing I can say is the feedback that we get from people who are beta testing these new features, that's a direct line into our engineering team because they read those comments and they make changes to those products before they come out, based on that feedback.
Bob: Yeah. I think this is great because there's so many things on our side we'll be able to share. Hopefully, I don't descend too many people up on Allen's talents, and he'll say, "Where are all these people coming from?" Well, I've been sharing your Slack channel, your handle and stuff, but hopefully that won't overwhelm you. We might even have to have occasional special episodes. You know, the Allen Smith update. It's that time of the year.
Brad: Allen Smith Hour. Come on in, if you've got a question.
Bob: Well, this has been good stuff. Yeah, there's a lot packed in there. A lot of stuff they can take advantage of, get involved with. I know I'm looking forward to working with Allen more. We've already connected and, yeah, there's a lot of good intertwining between WooCommerce and our mission here.
So if somebody's saying, "Hey, now I want to talk to Allen," where's the best place to connect with you?
Find Allen on WooCommerce Slack
Allen: The best place, I would say is reach out to me in Slack. If you join our Slack community, I'm pingable in there. You can ping me 24 hours a day. I don't always have my phone with me, but I try to get back to people within a reasonable timeframe, within a day or so. You can reach me in there. I'm just Allen Smith in Slack. The other thing is you can email at my email address is firstname.lastname@example.org. Those are probably the easiest ways to get in touch with me.
Bob: Excellent. I just want to thank a href="https://woocommerce.com/" target="_blank" rel="noreferrer noopener" aria-label="WooCommerce.com (opens in a new tab)">WooCommerce.com again for their support.
Also, if you are a builder, check out WooSesh next week, an online virtual conference, at Woosesh.com.
Well, I think that is a wrap. Do check out DoTheWoo.io, lots of stuff Here. I hope the site speaks for itself. So dive into that and see all the different things we have going on. Again, Allen, I appreciate you taking the time to join us.
Allen: Yeah. Thank y'all so much for inviting me on. This has been great.
Bob: All right. Well, thanks, everyone. Until next week. We'll see you then.
Sign up to receive email updates
Enter your name and email address below and I'll send you periodic updates about the podcast.