Imagine you have simply joined a brand new know-how firm, and one of many first duties you are assigned is to enhance and centralize the group’s developer-facing documentation. There’s only one catch: That documentation exists in many various locations, throughout a number of platforms, and differs markedly in accuracy, forex, and magnificence.
So how did we sort out this problem?
Understanding the scope
As with any challenge, we first wanted to know the scope and bounds of the issue we had been attempting to resolve. What documentation was good? What was working? What wasn’t? How a lot documentation was there? What format was it in? We wanted to do a documentation audit. Luckily, Aneta Šteflová had lately published an article on OpenSource.com about this, and it offered wonderful steerage.
Next, each piece of publicly going through documentation was assessed for the subject it lined, the medium it used, forex, and high quality. A sample shortly emerged that totally different platforms had main deficiencies, permitting us to make a data-driven method to decommission our current Jekyll-based websites. The audit additionally highlighted simply how fragmented our documentation sources had been—we had developer-facing documentation throughout no fewer than seven websites. Although search engines like google had been discovering this content material simply tremendous, the fragmentation made it tough for builders and customers of Mycroft—our major audiences—to navigate the data they wanted. Again, this knowledge helped us make the choice to centralize our documentation on to at least one platform.
Choosing a central platform
As a corporation, we wished to constrain the variety of standalone platforms in use. Over time, upkeep and maintenance of a number of platforms and integration touchpoints turns into cumbersome for any group, however that is exacerbated for a small startup.
One of the opposite enterprise drivers in platform alternative was that we had two major however very totally different audiences. On one hand, we had extremely technical builders who we had been anticipating would push documentation to its limits—and who would need to contribute to technical documentation utilizing their instruments of alternative—Git, GitHub, and Markdown. Our second viewers—finish customers—would primarily eat technical documentation and would need to accomplish that in an inviting, welcoming platform that was visually interesting and offered extra options similar to the flexibility to establish studying time and to offer suggestions. The capacity to seize suggestions was additionally a key requirement from our aspect as with out suggestions on the standard of the documentation, we’d not have a strong foundation to undertake steady high quality enchancment.
Would we be capable to establish one platform that met all of those competing wants?
We realised that two platforms lined all of our wants:
- WordPress: Our current web site is constructed on WordPress, and we have now some fairly strong WordPress abilities in-house. The flexibility of WordPress additionally fulfilled our necessities for performance like studying time and the flexibility to seize person suggestions.
- GitHub: Almost all of Mycroft.AI’s source code is available on GitHub, and our growth staff makes use of this platform every day.
But how might we marry the 2?
Integrating WordPress and GitHub with WordPress GitHub Sync
Luckily, our COO, Nate Tomasi, noticed a WordPress plugin that promised to combine the 2.
This was put by its paces on our check web site, and it handed with flying colours. It was simple to put in, had an easy configuration, which simply required an OAuth token and webhook with GitHub, and offered two-way integration between WordPress and GitHub.
It did, nevertheless, have a dependency—on Markdown—which proved slightly tougher to implement. We trialed a number of Markdown plugins, however every had a number of quirks that interfered with the rendering of non-Markdown-based content material. After a number of days of frustration, and even an try to custom-write a plugin for our wants, we stumbled throughout Parsedown Party. There was a lot partying! With WordPress GitHub Sync and Parsedown Party, we had built-in our two key platforms.
Now it was time to make our content material visually interesting and usable for our person viewers.
Reading time and suggestions
To implement the studying time and suggestions performance, we constructed a brand new page template for WordPress, and leveraged plugins inside the web page template.
Knowing the estimated studying time of an article prematurely has been proven to increase engagement with content and gives builders and customers with the flexibility to determine whether or not to learn the content material now or bookmark it for later. We examined a number of WordPress plugins for studying time, however settled on Reading Time WP as a result of it was extremely configurable and could possibly be simply embedded into WordPress web page templates. Our resolution to position Reading Time on the high of the content material was designed to provide the person the selection of whether or not to learn now or save for later. With Reading Time in place, we then turned our consideration to gathering person suggestions and rankings for our documentation.
There are a number of score and suggestions plugins obtainable for WordPress. We wanted one which could possibly be simply personalized for a number of use instances, and that would mixture or summarize rankings. After some experimentation, we settled on Multi Rating Pro due to its large characteristic set, particularly the flexibility to create a Review Ratings web page in WordPress—i.e., a central web page the place employees can evaluation rankings with out having to be logged in to the WordPress backend. The solely hole we bumped into right here was the flexibility to set the show order of score choices—however it’ll probably be added in a future launch.
The WordPress GitHub Integration plugin additionally gave us the flexibility to hyperlink again to the GitHub repository the place the unique Markdown content material was held, inviting technical builders to contribute to enhancing our documentation.
Updating the prevailing documentation
Now that the “container” for our new documentation had been developed, it was time to replace the prevailing content material. Because a lot of our documentation had grown organically over time, there have been no fashion pointers to form how key phrases and code had been styled. This was tackled first, in order that it could possibly be utilized to all content material. You can see our content style guidelines on GitHub.
As a part of the replace, we additionally ran a number of checks to make sure that the content material was technically correct, augmenting the prevailing documentation with a number of pictures for higher readability.
There had been additionally a few extra instruments that made creating inner hyperlinks for documentation items simpler. First, we put in the WP Anchor Header plugin. This plugin offered a small however essential operate: including id content material in GitHub utilizing the markdown-toc library, then merely copied in to the WordPress content material, the place they’d robotically hyperlink to the id attributes to every <h1>, <h2> (and so forth) factor. This meant that inner anchors could possibly be robotically generated on the command line from the Markdown content material in GitHub utilizing the markdown-toc library, then merely copied in to the WordPress content material, the place they’d robotically hyperlink to the id attributes generated by WP Anchor Header.
Next, we imported the up to date documentation into WordPress from GitHub, and made positive we had significant and easy-to-search on slugs, descriptions, and key phrases—as a result of what good is superb documentation if nobody can discover it?! A ultimate exercise was implementing redirects so that individuals hitting the previous documentation could be taken to the brand new model.
What subsequent?
Please do take a moment and have a read through our new documentation. We realize it is not good—removed from it—however we’re assured that the mechanisms we have baked into our new documentation infrastructure will make it simpler to establish gaps—and resolve them shortly. If you’d wish to know extra, or have options for our documentation, please attain out to Kathy Reid on Chat (@kathy-mycroft) or by way of email.
Reprinted with permission from Mycroft.ai.
