About the Client
LearnDash is a leading learning management system (LMS), trusted by Fortune 500 companies, educational institutions and non-profits around the world. It can be deployed on any WordPress site via a plugin.
Just like WordPress, LearnDash is designed to be extensible through a rich ecosystem of easy to install add-ons, and, on a deeper level, hooks, functions and APIs.
We know first hand how intuitive and extensible LearnDash is because our own WordPress training course is built on the platform. So when LearnDash (herein referred to as “LD”) approached us with an interesting project, we were particularly excited to do some Good Work.
A Completely Overhauled Codebase
LearnDash 3.0 (LD3.0) is the latest major release of the LMS. Throughout the many months of research, design, and development, the team’s primary focus was ensuring that all visual aspects of the release were intentionally and thoughtfully designed.
And this philosophy extended to an often overlooked area – software documentation.
Clear, up-to-date documentation is an essential part of any software release because it reveals the capabilities of the product. This not only eases the burden on first level support, but also provides developers with the information they need to write the extensions and integrations that are a necessary part of any vibrant software ecosystem.
Owing to the magnitude of code shipped with LD3, the majority of LearnDash’s existing software documentation was out-of-date at release. The process of updating this documentation, and keeping it updated, was a massive undertaking.
Addressing Duplicated Effort
rtCamp engaged with LearnDash to help them document their codebase – all 800+ hooks, functions and API calls. Even at a conservative estimate of one documentation page every half hour, it would take 400+ man-hours to complete!
Furthermore, documentation usually exists in two places – within the codebase itself (aka inline documentation blocks or docblocks), as well as on a dedicated public website. Though conveying a lot of the same information, these are usually written at different times during the product development lifecycle and thus require a duplication of effort.
During the initial stage of the project, rtCamp worked closely with LearnDash’s engineering team to complete a few docblocks, establish a convention, and settle on a standard way of documenting the different types of programming interfaces. Once that was out of the way, rtCamp started investigating how the documentation process could be automated in order to reduce the duplication of effort.
Creating An Automated System
All things considered, WP Parser proved to be a great starting point for LearnDash’s requirements. This parser is responsible for creating the new code reference at developer.wordpress.org and works by processing inline documentation and converting it to custom post type entries in WordPress. Modifying an existing plugin instead of starting from scratch removed tens of man hours worth of development and testing.
LearnDash was considering hosting its public documentation on Confluence; however, rtCamp’s WordPress-centered solution proved to be a better alternative since the powerful WP REST API is perfect for automations and LeanDash’s team was already comfortable with WordPress.
While WP Parser provided a solid base, it needed to be modified to fit into an automation that would run via a single click. rtCamp created two specialized scripts to help with this.
The Examples Import Script
The first script looks at the files within a special docs folder in the LearnDash plugin codebase to update code usage examples for hooks. The folder contains files that map existing hooks to their example files. These files are added during development.
REST API Docs Import Script
LearnDash provides a RESTful API to create, update, retrieve or delete quizzes created within the system. In order to document this API, rtCamp created a modified version of one of the scripts in the WP-API parser.
This script makes requests to LearnDash’s development website and generates HTML documentation files based on the responses. The documentation covers the API schema and endpoint arguments.
Putting It All Together
rtCamp tied all the components of the automation together via a simple admin interface on LD3’s documentation website. A few buttons provide the controls to run the different parsers and scripts.
When a new release comes along, it need only be added to the documentation website like any other plugin. Then, with just a few clicks, all changes to hooks, functions, or the LD3 REST API would be pulled straight from the plugin’s codebase and used to add or modify existing documentation pages. Once completed, an email notification would be sent to the provided email address.
The documentation website’s sitemap directly reflects the plugins’ codebase structure, making it much easier to track down parts of LearnDash’s codebase while building addons and extensions. The format of the doc pages themselves are immediately familiar to any WordPress developer because they follow the same conventions as developer.wordpress.org.
Efficient, Automated Documentation
rtCamp delivered a documentation process that automated an important but time-consuming part of maintaining any platform. The results were consistently of high quality and fit the conventions that LearnDash’s users had come to expect. At launch, the system reduced time-to-live for a doc page by an order of magnitude and will continue to save tens of hours in subsequent releases.
Highlight
- One-click automated technical documentation solution for a WordPress plugin
rtCamp is in the process of deploying this automation for all of LearnDash 3.0’s addons. Well-written and consistent documentation will not only reduce direct support tickets, but also help improve developer confidence in the product.
Have an interesting problem that needs solving? Feel free to reach us.