We code documents in this system using a lightweight code called AsciiDoc. We apply United Nations editorial style conventions and spelling (tl;dr: British English with –ize and –yse endings).
We use AsciiDoc because it means that:
-
Authors need not worry about maintaining formatting.
-
Changes to both the document’s content and structure can be tracked and managed using general tools.
-
The same source files can produce multiple outputs automatically, such as HTML and (as a convenience) PDF.
-
The management and tracking translations is easier and more efficient.
While this system does require learning some new tools, the ones we have chosen are widely used in the publishing, software development and translation communities. AsciiDoc is also relatively simple to work with and understand. If you’ve written or edited a Wikipedia article, you’ll have no problem with this format.
We’ve pulled out details for a few of the more common uses of AsciiDoc markup in the technical guidelines below to give you a flavour of it. However, two resources provide more detailed guidance:
-
The AsciiDoc Writer’s Guide, which provides a ‘gentle introduction’ to the format
-
The AsciiDoctor User Guide, which provides a comprehensive reference on how to work with this language.
If you have questions, comments or concerns—either specifically about AsciiDoc or about the overall use and approach of this format—please email us at [email protected].