In part of a podcast with Allen Smith, developer advocate at WooCommerce, we dove a bit into the latest updates on their docs and resources. Here are some insights of what has happened and how it’s staying updated.
The Developer Documentation and Resources on WooCommerce
To make the move of updating the resources and docs, for WooCommerce, specific things stood out from the developer community.
Specific Needs from the Developers
First 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. As a result, these are the pieces that their focusing on right now.
The next phase is creating the new content focused on the technical guidance they can provide. Their goal here is to be assured that community are using the best practices for developing for the platform. This can be adhering to certain linting guideline and documentation standard to make sure that they’re developing against the platform in a way that they describe as future-proof. The result of that is aimed to avoid their extensions being stomped out when the platform changes.
Also, they want to make sure that the work that developers are doing is constantly providing that first-class experience to merchants. It was pointed out that 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 WooCommerce is trying to do is respect that extensibility in a way that still provides that seamless customer experience and merchant experience.
Keeping the Docs Updated
To tackle the notion of keeping documentation updated, the WooCommerce team is busy with the process.
For instance, the reference docs have been recently updated. If you go to the WooCommerce core, it’s the core code reference basically. That entire site has been redesigned. What they will do now is 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.
As noted, 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.
You can listen to the entire episode with Allen here.