Google Season of Docs: Metanorma

Problem

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.

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.

Goals

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

• Reduce support queries by creating a training that teaches new users how to create a document, troubleshoot it, and publish it.
• Create a clear information architecture that increases findability.

Process

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.

   

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

   

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.

Challenges

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

• Scope creep
  In the beginning, the project's goals left some room for interpretation. Because I felt very passionate about this project, I wanted to do everything and then and more. However, I had to learn to further specify, and negotiate deliverables to not fall victim to scope creep. Leaving the documentation in a better state than before is more important than making everything perfect.
• Letting code go stale
  You might have noticed that a lot of work went into the project but you can't see much of it on the Metanorma website. After the initial three months we planned for the project, my personal circumstances changed and I could no longer contribute.
  However, six months later, I was able to contribute again and I checked in with the team if they had merged my branch. While I was away, the team made changes to the main documentation that broke the changes I had originally in mind, preventing a clean merge.
• Team mates dealing with competing priorities.
  Initially, when the project kicked off, it was me and another tech writer taking care of the documentation. However, the other writer was caught up in many projects aside from their full-time job. Knowing they had a full plate, I would check in regularly and ask how we can make the project work. I assigned clear tasks along with deadlines which often weren't met. Once I dealt with my own tasks, I would help out with theirs.