EDITING



# Editing guide

This is a guide for reliably editing text-heavy documents.


## Works

This guide distinguishes between the following works:

Master text
:    document with semantic markup.

Final document
:    document with presentational markup.


## Roles

This guide distinguishes between the following roles:

Author
:    Write master texts.

Editor
:    Select and prepare master texts for further processing.

Designer
:    Compose visual presentation from master texts.

Each role is distinct.
Participants may have multiple roles, but only one at a time.


## Responsibility

Authors are responsible for master texts they write.

Designers are responsible for visual presentations they compose.

Editors are responsible for coherence of content and its presentation.

Authors and editors may refine markup in quotations
(e.g. replace "ASCII art" styling of lists with semantic equivalent),
while preserving their verbatim representation.

Editors may fix typos and wrong or weak markup of master texts,
while preserving their communication style.


## Editing markup

Editing markup serves 2 purposes:

  * Allow designer to recognize semantics of master text.
  * Allow (author and) editor to proof-read and refine master text.

Consequently, editing markup should be semantic and unambiguous.

In particular, do *not* trust visual presentation in authoring tools.


## Wiki-like editing markup

Editing markup suitable for Markdown or Mediawiki.

Below syntaxes may not be used for any other semantic purpose.

### Dash

  * Use `--` (hyphen-minus x 2) for sentence break or parenthetical statement.
  * Use `-` (hyphen-minus) for ranges or minus.
  * Avoid fancy dash or hyphen (difficult to proof-read or process).

### Emphasis

  * Surround `*` `*` or `''` `''` (emphasis) in general.
  * Surround `*"` `"*` or `''"` `"''` (emphasis + doublequote) for technical or foreign term.
  * Surround `"*` `*"` or `"''` `''"` (doublequote + emphasis) for title.
  * Surround `**` `**` or `'''` `'''` (strong emphasis) for essential keyword.

### Links

  * Use canonical URL (not relative, wiki-URL, redirection or backup).
  * Surround `<` `>` (angle bracket) for bare URL.
  * Avoid archive URL (except as such: archiveurl keyword in citation).
  * Avoid relative or redirection URL.

### Comment or note

  * Surround `[` `]` (square bracket) for meta comment.
  * Surround `[^`[note][] `]` or `<`[ref][] `>` for foot-/end-/sidenote.

[note]: http://johnmacfarlane.net/pandoc/README.html#footnotes
[ref]: https://meta.wikimedia.org/wiki/Help:Footnotes

### Quotation

  * Surround `"` `"` (doublequote) in general.
  * Use `<blockquote>` for full paragraph or when crossing paragraphs.
  * Surround `'` `'` (singlequote) within another `"`-surrounded quote.
  * Use `[...]` (dot x 3 in square brackets) to indicate skipped chunk.
  * Append citation immediately after each quote.
  * Avoid curly quotes (difficult to proof-read or process).

### Citation

  * Prepend `---` (hyphen-minus x 3) on separate line for simple citation.
  * Use `{{`[cite][] `}}` to embed bibliography.
  * Avoid fancy dash (difficult to proof-read or process).

[cite]: https://en.wikipedia.org/wiki/Help:Citation_Style_1

 -- Jonas Smedegaard <dr@jones.dk>  Tue, 13 Jan 2015 02:13:31 +0100