Reviewers Edition

The Reviewers Edition system is a predictable, readable, and computable way to mark versions of useful prose documents, like policies and legal forms. Reviewers Edition numbers give document authors a simple, clear, and concise way to tell document users how much has changed, and what they should review, as documents evolve over time.

Editions

Reviewers Editions are written in short codes, like 1e. You can read this code “first edition”—1 for “first” and e for “edition”. 12e is “twelfth edition”. And so on.

Publishing an edition, like 9e, followed by a higher-numbered edition, like 10e, sends a specific message to users. Users of 9e should review the entire text of new 10e to decide if it meets their needs, as 9e did.

Updates

Authors often update documents to add or remove material, leaving most of the document the same. Reviewers Editions like 1e1u, read “first edition, first update”, or 10e15u, read “tenth edition, fifteenth update”, describe these changes.

Publishing a new update to an old edition sends a specific message to users. Users of a 10e should compare new 10e1u to old 10e, and review what has changed, to see whether the new update meets their needs. Users of a 10e7u should compare a new 10e10u and review what has changed. But users of a 10e should review a new 11e1u top-to-bottom, since the author used a higher edition number, as well.

Corrections

Some changes to useful documents don’t add, remove, or change meaningful pieces of language, but merely correct spelling, structural, or other technical errors. Reviewers Editions like 3e1c, read “third edition, first correction”, or 7e11u3c, read “seventh edition, eleventh update, third correction”, describe these changes.

Publishing a new correction to an old edition or update sends a specific message to users. Users of a 10e should prefer to use 10e1c, and can do so without reviewing the changes. Of course, users may always choose to review the changes. But correction numbers in the Reviewers Edition system allow authors to communicate when changes go to correctness, rather than content.

Drafts

Document authors often create working drafts before publishing. Reviewers Editions like 8e1d, read “first draft of eighth edition”, or 2e1u5c3d, read “third draft of second edition, first update, fifth correction”, describe these drafts.

Publishing a new correction to an old edition, update, or correction sends a specific message to users. Users of a 10e3u should continue to use 10e3u, even when 10e3u1c1d, 10e3u4d, or 11e15d are available. Authors working together to create a 13e should review 13e7d instead of old 13e6d.

Review

Reviewers Edition numbers are written as codes, like 3e4u1c2d:

                3e  4u  1c  2d

                │   │   │   │
third edition ──┘   │   │   │
                    │   │   │
    fourth update ──┘   │   │
    (optional)          │   │
                        │   │
     first correction ──┘   │
     (optional)             │
                            │
             second draft ──┘
             (optional)

Changes to the four numbers send different messages to users:

Computer Software

Even if you don’t write computer software yourself, you should know that Reviewers Edition codes are easy for computer programs to read and interpret. This makes it possible to write computer programs to analyze documents marked with Reviewers Edition codes.

Software procedures to parse, create, interpret, compare, and explain Reviewers Edition codes are currently available in the JavaScript programming language.