Improving Actions on Google reference documentation with the new Typedoc Neo theme
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.
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.
To do this, we added several links to our typedoc.json configuration as shown in the snippet below:
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.
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.
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.
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.
We specified regular expressions for the pages that we want to highlight, as shown in the snippet below:
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.
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/.