search

metanorma / metanorma.org

Official Metanorma website
https://www.metanorma.org
MIT License
7 stars 7 forks source link

Some documentation contribution on why Metanorma #76

Open ronaldtse opened 5 years ago

ronaldtse commented 5 years ago

Had to write this for someone so here it is:

What is Metanorma

Metanorma is an authoring and publishing tool that is specifically for Standards Development Organizations (SDOs).

Metanorma is actually not just an authoring tool. It provides (a) a document model (the Metanorma StanDoc model), (b) a document schema for the SDO, (c) and tools that help generate documents in the SDO's format. The flow goes: "text input" -> "Metanorma XML" -> "output formats". So the generation of output formats from Metanorma XML is only one part of it.

Value of Metanorma to authors

  1. What you write is what you mean. Metanorma separates the author's concerns of content vs presentation. All the author needs to focus on is content. Presentation, formatting and layout is the responsibility of Metanorma.

Metanorma XML is a "semantic" format, meaning that all text elements are encoded in a logical structure that represents the standard. For example, in Word, a "Clause" is represented by a paragraph. In Metanorma, a "Clause" is represented as a "clause". What this means is every structural element of the standard can be directly referred to. This is not possible in other formats, including Word and LaTeX.

  1. End-to-end authoring visibility. Usually, an author cannot see the final output of the SDO publication. The SDO has an editorial team that deals with publication. The author has to pass the master copy to the SDO editor, and the editor publishes the document. However, if the editor changes things, which is very often, the author will not know, and often have to do line-by-line proof reads. With Metanorma the author can fully know what will be published.

This allows the author to rapidly iterate the document content.

  1. Metanorma provides a number of automation features, including: auto-fetching of bibliographic entries, citation support.

  2. Assistance features such as validation and application of the SDO's editing rules. For example, in ISO, a term definition is not allowed to start with an "article" like "a", "an", "the". Metanorma warns you automatically.

  3. Metanorma works with pure/plain text documents. This allows authors to use software versioning tools and a continuous integration workflow to author and publish documents.

  4. Metanorma works on Windows, Linux, macOS.

Value of Metanorma to SDO

  1. Authoritative format. The document delivered by the author is the exact same one to be published. In many SDOs, the editor has to copy and paste the content into some new template or specialized tool in order to publish the document. Things go wrong with copy and paste and the subsequent editing by the editor. With Metanorma, the author only has to deliver the XML file to the SDO, and the SDO can directly publish it without any further effort.

  2. The SDO does not need to maintain technical "editing" personnel. The toolchain used by the author and the publisher is identical.

  3. Metanorma helps authors easily publish at more than one standard organization. For example, industry SDOs often publish documents to international SDOs. Metanorma allows them to use the same content to publish at different places.

  4. Metanorma is in plain text, and therefore allows SDOs to use continuous deployment workflows to publish the documents.

  5. Metanorma is open-sourced and open-licensed -- SDOs can finally publish documents for free.

sgilsonator commented 5 years ago

@ronaldtse do you have a context for where you are thinking of using this content?

ronaldtse commented 5 years ago

@doktorgee this is the "selling" part of Metanorma.

The first part for Authors illustrates some key goals / features of Metanorma for the author.

The latter part for organizations is how we convince them to adopt Metanorma.