Google Season of Docs: Metanorma

About the Project

Google's "Season of Docs" program emphasizes the critical value documentation provides by fostering collaboration between open-source projects and technical writers.
Metanorma is a free, open-source authoring toolchain for technical standards, such as those developed by ISO and IETF. It provides extended AsciiDoc markup capabilities and metadata models to support editors in adhering to the stylistic rules of their organization.

During the three-month project, I proposed a new information architecture for Metanorma's documentation to improve findability. To lower Metanorma's adoption barrier, I created a 26-lesson curriculum geared towards new users. To make the Metanorma documentation future-proof, I laid out a roadmap.


Image of an AsciiDoc document that gets compiled into HTML and PDF.
Fig. 1 - Metanorma takes AsciiDoc input which can be rendered to different formats with distinct styling.

Since most standard contributors author their documents in Word, they are used to working with a graphical user interface. Metanorma doesn't have buttons to format text - you need markup to do that. Users write text in AsciiDoc and Metanorma compiles different outputs, such as XML, Word, HTML, and PDF. To generate a document, you need to compile the source text using the Metanorma command line tool. Thus, new users are often struggling to adopt Metanorma and reach out to the project maintainers directly for support.

Layers of complexity in Metanorma.
Fig. 2 - Layers of complexity in Metanorma.

Metanorma uses AsciiDoc as a markup language. However, to provide features that standards organizations need, they extended the set of markup instructions. This extension is called "Metanorma AsciiDoc". For each standard organization, there are different rules to form a conformant document. An ISO standard takes requires different metadata than an IETF standard. This layered approach makes sense from an engineering perspective, however, even experienced users have difficulties finding the specific documentation they need.


To address the problems stated above, the project wanted to achieve two goals:


The project took three months from the initial analysis to the creation of a roadmap for the future. These were the steps I took:

  1. Organization
    The project should be completed within three months. I created a project plan to define tasks and assign them between me and my co-writer. Since the workload was quite high, we had to prioritize based on what we thought was the most important work. If there was time left, we would tackle the rest of the tasks.
  2. Research
    During the first month of the project, I made myself familiar with the toolchain, the documentation and our users.
    • User interviews: To understand the target audience and their needs, I conducted user interviews.
    • Quantitative audit: Together with my co-writer, I reviewed 94 documentation sources, mapping their location, gathering metadata and scanning for obvious issues.
    • Qualitative audit: To find out about common stylistic issues, I've analyzed representative samples using the Hamburg comprehensibility model.
    Analysis of the Quickstart guide.
    Fig. 3 - The qualitative audit revealed that the Quickstart guide is geared towards more experienced users than novices.
  3. Developing a new information architecture
    The content audit and user interviews revealed that the documentation lacked a well-defined structure on the site-level. Users often didn't know where to find the information they needed. To make matters worse, the site's search function was broken.
    To improve the findability, I restructured the site's information architecture to align with the Metanorma workflow. Roughly, the new site's structure would look like this:
    • Concepts
    • Creating a new Metanorma document
    • Editing Metanorma documents
    • Reviewing documents
    • Generating output
    • Troubleshooting
    • Reference documentation
    • Glossary
    The new information architecture.
    Fig. 4 - The new information architecture follows the Metanorma workflow.
  4. Create training material
    One of the main goals of the project was to assist new users with learning Metanorma. I created a curriculum consisting of 26 lessons with exercises to cover basic concepts and the Metanorma workflow. Have a look at the content on Github!
  5. Create a roadmap
    Since Season of Docs was practically the kick-off project for more documentation initiatives to come, I developed a roadmap for future improvements for the project.


We only grow by overcoming challenges. These are the main challenges I faced during the project and what I learned from them.

Return to home page