Improving Actions on Google reference documentation with the new Typedoc Neo theme

Nick Felker
Apr 9, 2019 · 5 min read

When the Actions on Google Node.js library migrated from version 1 to version 2, it was rewritten in TypeScript, a superset of the JavaScript programming language which is transpiled to JavaScript. As part of this development, we used a tool called TypeDoc to generate reference documentation.

When we began hosting the docs, several issues with the theme appeared. The default theme made it difficult to quickly get to the documentation that developers wanted, and I began to draft an improved module that would provide a better user experience.

Recently this work was released as an open source project on GitHub called the Typedoc Neo theme. Any developer can get the library through npm by running npm install typedoc-neo-theme.

In this blog post I’ll go through some of the big changes and how they make it easier for Actions on Google developers to read our reference documentation.

Browsability and navigation

The original theme had two sets of table of contents, both aligned to the right of the page. The first was the table of contents for a specific module, listing the classes, interfaces, and other features using iconography. The second was the global navigation, letting a developer find all of the modules.

Concatenating both lists made it difficult to read and find the page or content that you wanted. The Actions on Google library in particular had several modules that weren’t important for external developers, which meant that several of the list items were unhelpful. The pages that were more important had to be found by clicking several links in the content.

In the revised theme, the tables are split in two. The left-hand side displays a global navigation, and the right-hand side displays the page navigation.

Image for post
Image for post

The table of contents on the left-hand side is customizable. Based on what’s most important for developers, we have crafted a list of pages based on our typedoc.json configuration. You can see how we have created a nested structure for navigation in the snippet below:

Another new feature is the addition of several links at the top of the page. These can point to other documentation. In this page, it replicates the top-level pages in the Actions on Google documentation, making it easier for developers to find other useful content for building their Action.

Image for post
Image for post

To do this, we added several links to our typedoc.json configuration as shown in the snippet below:

Readability

In the old theme, the page navigation had icons next to the name of each feature. To know whether a feature of the module was an interface or a class, you had to look at the icon and consult a legend at the bottom of the page. This made it difficult to follow.

In the revised right-hand menu, the icons have been de-emphasized and headings at the top let the reader know which are classes and which are interfaces. The addition of this text makes the module easier to understand without needing to have esoteric knowledge. The menu is also sticky, so it remains easy to browse even as one scrolls down the page.

Another readability challenge was around the default link color, which was a light blue. This blue has a contrast ratio of 2.56, which can be difficult to read for those who don’t have good eyesight.

Image for post
Image for post
Original reference documentation
Image for post
Image for post
Current reference documentation

The new default link color is teal, which has a higher contrast ratio which passes the level AA standard. It is easier to read and puts less strain on your eyes. For reference material, which developers may consult frequently, this is a useful improvement.

Search

Searching was another area that could be improved. While searching for a particular feature, like a BasicCard, developers could find themselves discovering internal types and parameters that could mislead them on how to actually implement it.

While being able to access these internal types could be useful, we wanted to nudge developers towards pages that would be more relevant for them.

Image for post
Image for post

When looking at new ways to visualize search results, the Android Developer site was taken as an inspiration. Searching for a common keyword will provide a series of pages with additional metadata such as the API level and the category of content. This search functionality can be useful for finding the right page, and we discussed how to bring the same type of feature to our reference docs.

In the new theme, a set of search results have been marked as high priority. These results appear with an additional label such as “Rich Response”. Other results have been deprioritized. While they still appear, they are de-emphasized to bring attention to other results.

Image for post
Image for post

We specified regular expressions for the pages that we want to highlight, as shown in the snippet below:

Conclusion

The Typedoc Neo theme will continue development as needed to bring a high-quality docs experience for developers for the Actions on Google library and other libraries that developers may build.

To view the project on GitHub, which includes documentation on how to use it and build it yourself, visit https://github.com/google/typedoc-neo-theme. It’s also available via npm.

If you are interested in browsing the Actions on Google documentation, which has been using the new theme, you can visit https://actions-on-google.github.io/actions-on-google-nodejs/.

Google Developers

Engineering and technology articles for developers, written…

Nick Felker

Written by

Social Media Expert -- Rowan University 2017 -- IoT & Assistant @ Google

Google Developers

Engineering and technology articles for developers, written and curated by Googlers. The views expressed are those of the authors and don't necessarily reflect those of Google.

Nick Felker

Written by

Social Media Expert -- Rowan University 2017 -- IoT & Assistant @ Google

Google Developers

Engineering and technology articles for developers, written and curated by Googlers. The views expressed are those of the authors and don't necessarily reflect those of Google.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store