Rocking the docs: improving Mycroft's documentation

Originally published at: http://mycroft.ai/blog/improving-mycrofts-documentation/

Imagine you’ve just joined a new technology company, and one of the first tasks you’re assigned is to improve and centralize the organization’s developer-facing documentation. There’s just one catch! That documentation exists in many different places, across several platforms, and differs markedly in accuracy, currency and style.

So how did we tackle this challenge?

Understanding the scope

Just like any project, we first needed to understand the scope and bounds of the problem we were trying to solve. What documentation was good? What was working? What wasn't? How much documentation was there? What format was it in? We needed to do a documentation audit. Luckily, Aneta Šteflová had recently published an article on OpenSource.com about this - and it provided excellent guidance.

 

[caption id=“attachment_33646” align=“alignnone” width=“1603”]audit Mycroft documentation audit, showing source, topic, medium, currency, quality and audience[/caption]

 

Next, every piece of publicly facing documentation was assessed for the topic it covered, the medium it used, currency and quality. A pattern quickly emerged that different platforms had major deficiencies, allowing us to make a data-driven approach to decommission our existing Jekyll-based sites. The audit also highlighted just how fragmented our documentation sources were - we had developer-facing documentation across no less than seven sites. Although search engines were finding this content just fine, the fragmentation made it difficult for Developers and Users of Mycroft - our primary audiences - to navigate the information they needed. Again, this data helped us make the decision to centralize our documentation on to one platform.

Choosing a central platform

As an organisation, we wanted to constrain the number of standalone platforms in use. Over time, maintenance and upkeep of multiple platforms and integration touchpoints becomes cumbersome for any organization, but this is exacerbated for a small start-up. One of the other business drivers in platform choice was that we had two primary but very different audiences. On one hand, we had highly technical Developers who we were expecting would push documentation to its limits - and who would want to contribute to technical documentation using their tools of choice - Git, GitHub and Markdown. Our second audience - end Users - would primarily consume technical documentation and would want to do so in an inviting, welcoming platform that was visually appealling and which provided additional features - such as the ability to identify reading time, and to provide feedback. The ability to capture feedback was also a key requirement from our side - as without feedback on the quality of the documentation we would not have a solid basis to undertake continuous quality improvement.

Would we be able to identify one platform that met all of these competing needs?

We realised that two platforms covered all of our needs:

  • WordPress: Our existing website is built on WordPress, and we have some reasonably robust WordPress skills in-house. The flexibility of WordPress also fulfilled our requirements for functionality like reading time and the ability to capture User feedback.
  • GitHub: Almost all of Mycroft.AI's source code is available on GitHub, and our development team use this platform daily.
But how could we marry the two?

Integrating WordPress and GitHub with WordPress GitHub Sync

Luckily, our COO, Nate Tomasi, spotted a WordPress plugin which promised to integrate the two.wordpress github sync

This was put through its paces on our test website, and passed with flying colors. It was easy to install, had a straightforward configuration, which just required an oauth token and webhook with GitHub, and provided two-way integration between WordPress and GitHub.

It did however have a dependency - on Markdown - which proved a little harder to implement. We trialled several Markdown plugins, but each had several quirks that interfered with the rendering of non-Markdown based content. After several days of frustration, and even an attempt to custom-write a plugin for our needs, we stumbled across Parsedown Party. There was much partying! With WordPress GitHub Sync and Parsedown Party, we had integrated our two key platforms.

Now it was time to make our content visually appealling and usable for our User audience.

Reading time and feedback

To implement the Reading Time and Feedback functionality, we built a new Page Template for WordPress, and leveraged Plugins within the Page Template.

Knowing the estimated reading time of an article in advance has been proven to increase engagement with content - and provides Developers and Users with the ability to decide whether to read the content now, or to bookmark it for later. We tested several WordPress plugins for reading time, but settled on Reading Time WP because it was highly configurable, and could be easily embedded into WordPress Page Templates. Our decision to place Reading Time at the top of the content was designed to give the User the choice of whether to read now or save for later. With Reading Time in place, we then turned our attention to gathering User feedback and ratings for our documentation.

Reading Time WP in action

multi-rating-pro

There are several rating and feedback plugins available for WordPress. We needed one that could be easily customized for several use cases, and which could aggregate or summarise ratings. After some experimentation, we settled on Multi Rating Pro, because of its wide feature set, especially the ability to create a Review Ratings page in WordPress - ie a central page where staff can review ratings without having to be logged in to the WordPress back end. The only gap we ran into here was the ability to set the display order of rating options - but it will likely be added in a future release.

The WordPress GitHub Integration plugin also gave us the ability to link back to the GitHub repository where the original Markdown content was held, inviting technical Developers to contribute to improving our documentation.

Updating the existing documentation

Now that the 'container' for our new documentation had been developed, it was time to update the existing content. Because much of our documentation had grown organically over time, there were no style guidelines to shape how keywords and code were styled. This was tackled first, so that it could be applied to all content.
You can see our content style guidelines on GitHub
As part of the update, we also ran several checks to ensure that the content was technically accurate, augmenting the existing documentation with several images for better readability.

There were also a couple of additional tools that made creating internal links for documentation pieces easier. First, we installed the WP Anchor Header plugin. This plugin provided a very small, but very important function - adding id attributes to each <h1>, <h2> (and so on) element. This meant that internal anchors could be automatically generated on the command line from the Markdown content in GitHub using the markdown-toc library, then simply copied in to the WordPress content, where they would automatically link to the id attributes generated by WP Anchor Header.

Next, we imported the updated documentation into WordPress from GitHub, and made sure we had meaningful and easy-to-search on slugs, descriptions and keywords - because what good is excellent documentation if no one can find it?! A final activity was implementing redirects so that people hitting the old documentation would be taken to the new version.

What next?

Please do take a moment and have a read through our new documentation. We know it isn't perfect - far from it - but we're confident that the mechanisms we've 'baked in' to our new documentation infrastructure will make it easier to identify gaps - and resolve them quickly. If you'd like to know more, or have suggestions for our documentation, please do reach out to Kathy Reid on Chat (@kathy-mycroft) or via email.

 

3 Likes

That looks great, and very helpfull indeed!

1 Like

This effort is very appretiated!
For newcomers find the correct, updated and useful information is a complete challenge right now. from those all scatterd places… And I can see there is a procedure to change Mycroft’s default language! YAY!

1 Like

This is great work from a great team. Thanks for all of the effort Kathy.

1 Like

congratulations for the wonderful work!!

I’m trying to read all the pages you’ve made available to give you all the feedback I can
but i do not know how to explain clearly… so sorry for my poor english

now I’m reading and testing : [Language support in Mycroft - Italian - italiano](http://Language support in Mycroft - Italian - italiano)

but I do not understand if you refer to Mycrof in generally or as linux enclosure, so for me is not clear if this doc is good also for Picroft and other enclosure

for example in Picroft the first command : mkdir -p /usr/local/share/pocketsphinx/model/it/it
it’s rejected (I think for permission on folder,)

but there are other small error like :

bla bla …file is archived within the cmusphinx-it-5.2.tar.gz file in the path /cmusphinx-it-5.2/etc/ voxforge_it_sphinx.ml

Check that this file has been extracted into /usr/local/share/pocketsphinx/model/it
Verify the installed files …Check that the following files exist:usr/local/share/pocketsphinx/model/it/it-small.lm

but the rename command is missing?!?!?!

now the question:
what is the right way to report if the doc is not clear or if there are errors on the page?

  • doc rating && comments?
  • email?
  • forum?

bye
Ale

the language support docs all use instructions from a old wiki entry that requires some unmerged/old/outdated pull requests, they also talk about pocketsphinx in lenght which is not required (and there are 3 separate PRs for that!)

someone correct those asap, first things new users will do is try to change mycroft to use their mother language

Hi @aleale99 thanks so much for your feedback, really appreciated.
The language docs have some errors in them, as I haven’t been able to figure out which parts of the documentation are in error - so your feedback will definitely help with that.

The key piece of information here is that the language docs refer to th Mycroft for Linux installation, not Picroft, which is where you may have run into problems.

I’m about to update the language docs to let people know that the docs refer for Mycroft for Linux - we don’t have instructions yet for changing the language on Picroft - we’d really love some assistance with that.

You can report issues with the Docs any way you’re most comfortable with - the Doc Rating and Comments go to all of us here, and then I prioritize updates, the Forum is a great place and our Chat - https://chat.mycroft.ai - has a dedicated ~languages channel too.

Kind regards,
Kathy

Thanks @Jarbas_Ai for your feedback - I still need to know exactly what needs to be changed in the documentation … - is that something you might be able to help with?

Kind regards,
Kathy

what is the best way to give feedback about the docs?

i tried leaving feedback in the docs page, but i can only give once per page, doesn’t seem the right place to report mistakes, i am now opening issues in the repo

my take on what needs changing in language support https://github.com/MycroftAI/docs-rewrite/issues/8

2 Likes