/gsod

Metanorma’s Google Season of Docs 2021

Purpose

Metanorma is a participant in the Google Season of Docs (GSoD) 2021.

This repository is used to organize work relating to our GSoD projects.

See our original project proposal for more details.

Participating tech writers

  • Ankita Tripathi (@techtrailhead)

  • Tina Lüdtke (@kickoke)

For more details, see the kickoff post.

Project schedule

TBD.

Deliverables

  1. Audit report of the current state of documentation

    1. Familiarize and audit existing documentation and software

    2. Develop an understanding of existing community needs

    3. Strengths and weaknesses of current documentation

  2. Information architecture

    1. The desired information architecture should:

      1. Allow the audience to discover the information they need;

      2. Use a layered approach, where the audience can learn more detailed information step-by-step, allowing the novice to progress in knowledge without being overwhelmed; and

      3. Be understandable to laymen. Most Metanorma users are standardization experts and professionals in diverse industries — they cannot be expected to have a level of computer knowledge comparable to that of developers.

  3. Metanorma authoring guide for new users

    1. Consolidate information across existing documentation, covering these topics:

      1. Introduction to Metanorma;

      2. A “quick start” that allows new users to get up and running quickly, with pointers to existing documents where appropriate;

      3. Flavors of Metanorma and their authoring guidance (see next deliverable);

      4. Metanorma standards and specifications; and

      5. A list of related tools and guidance of their usage

  4. SDO-specific authoring guides for IETF, OGC, ISO and another organization

    1. Covering the topics of:

      1. Introduction to the usage of Metanorma in the SDO

      2. Describe the publication flow of a standard at the SDO, and where Metanorma applies within that workflow

      3. Provide authoring guidance on how to author a standard for that SDO, including pointers to existing reference guides

      4. Provide actionable guidance on how to submit the Metanorma-created standard to the SDO for publication

    2. Able to publish them as separate documentation sites for the SDO-specific audience

  5. GSoD project case study (one per technical writer)

    1. Authored by the technical writer and interested project mentors

    2. Describes the success and challenges faced during the GSoD project for future reference

Identified issues

  1. Lack of a general authoring guide, especially geared towards the novice author.

    • New Metanorma users have pointed out the lack of an authoring guide that guides the novice on the steps on setting up the environment, on creating a document, and on preparing a document for publication. Visitors to the site have indicated that it is easy to be overwhelmed by the number of repositories and specifications at first glance.

  2. Lack of flavor-specific authoring guides.

    • Standards authors use Metanorma to create SDO-specific standards, for example, IETF or OGC. Each SDO applies different encoding requirements and content rules on their standards and requires different metadata elements to be entered. While Metanorma does provide reference documentation, they are not sufficient to initiate the author of a standard who is new to Metanorma.

  3. Unintuitive information architecture.

    • Existing Metanorma users have suggested that the information requested is often scattered across multiple locations. One may need to go back and forth across several documents to find the desired information.

  4. Non-development direct enquiries.

    • New users often directly contact project contributors via email or create issues at the GitHub repositories for information they could not locate in the documents. Most of these topics are actually covered on the project website, but they can be difficult to locate for new users.

References