Evaluation of the Current State of the Docs

I started by studying the current docs site (which I helped create in 2021) and came to the following conclusions:

• The site is organized by topic, so audiences are mixed. This makes it hard to find information.
• Some of the guides are very shallow, they have been placeholders waiting for content for a very long time.
• The 6 top-level sections are confusing: there’s too many of them and little information to help you choose. Also, they do not match the menu on the left.
• The structure is unclear: Top navigation bar does not match left menu. Some pages are very hidden (like the SDKs). Some of the pages in the Employee Handbook should really be public for everybody.
• Some sections are outdated, like the Python SDK, or even deprecated, like the old JS and Java SDKs.

Given that a rewrite of most of the pages is required, I proposed to create a completely new site.

New Site Proposal

• Use three clearly-separated top sections for the different audiences:

  • User Guides: How to perform different actions without code (Wallet guides, for example).
  • Developer Guides: How to perform different actions using code (Tutorials).
  • Textbook: Explains the technology behind everything.

  

  These are just some concepts and will not be the final images.

• Add some more features:

  • Glossary tooltips, so readers don’t need to leave a page to know the meaning of an acronym.
  • Syntax-highlighted code snippets, verified from the Continuous Integration pipeline, in different programming languages.
  • Embedded API and SDK reference docs, so they don’t look like a different site. Tutorials should be able to link to specific methods and classes, and provide tooltips with their description.
  • Light and Dark mode support.
  • Small screen support.
  • Internationalization support (at least, Japanese).

These are all the features that I would like to have. I am not making any guarantee here, other than I will try my hardest to have all of them implemented.

Work Done So Far

First off, I’ve studied different documentation frameworks. The old docs use Sphinx, which I like a lot, but I wanted to research more options like GitBook or Docusaurus. In the end, I settled for MkDocs using the Material theme because it is a combination I know very well, and I am confident it can handle the features I have in mind. Moreover, it provides some of the features out of the box, like support for themes, small screens, and internationalization.

I then created a new MkDocs project, gave it an initial page structure, and started adding plugins to provide the rest of the desired features:

• ezglossary: Tooltips for glossary entries, but also reference docs.
• mkdocstrings: API docs straight from source code, combined with mkdocstrings-python, mkdocstrings-typescript, and mkdoxy for Java support.
• Some more auxiliary plugins like meta-manager, gen-files, literate-nav, git-authors…

Some of the tested plugins worked out of the box, some others clashed between them, and some others are still under development, so it took some experimentation to find the right combination.

I am currently fighting with some of the autogenerated docs, and waiting for the artists to provide some images to spice up the site. Once that is fixed, I should be able to share a working proof-of-concept of the new site 🙂

Up Next

Once I am confident the tool can support everything I want to do, I’ll create the detailed task list of all the pages that need to be added, probably onboard another writer, and start writing!

OK, back to the trenches! Feel free to provide feedback or discuss my decisions, and see you next month!