[ncc-services-wg] Pre-PDP discussion: "All RIPE documents should be plain text"

* Richard Hartmann

> this is the first in a series of emails which I hope will advance into
> PDPs and then updated policies. Some of them are closely related, but
> I submit them individually so that if there are any hold-ups with a
> specific one, the other ones can still progress.
> 
> My first suggestion is:
> 
>   The canonical and binding format of all documents is plain text in
> UTF-8 encoding.
>   If a document can not reasonably be stored as plain text,
> PDF/A-1a[1] will be used.
>   If any document exists in both plain text and PDF/A-1a, plain text is binding.
>   Any other form is considered non-binding as soon as a plain text or
> PDF/A-1a variant exist.
>   All legacy documents which are still valid or relevant to current
> policies will be transformed within a year of this proposal becoming
> policy.
> 
> The reasoning behind this should be obvious: Ensure that all documents
> will be in the most simple-to-parse format now and forever.

Having recently authored a rather intrusive policy proposal that touches
a lot of text, I can only strongly agree with this. The pre-publication
procedure appears to be to send complete versions of the proposed new
policy document back and forth by e-mail (sometimes in different
document formats), with no easy way to pinpoint exactly what has changed
between the various versions. This makes the entire process needlessly
time-consuming, and increases the risk that some typo or mistake
accidentally sneaks into the proposal and makes it all through the PDP.

So there should definitively be an authoritative, easy to collaborate on
source format for all RIPE documents. Plain text is one obvious
alternative, but would preclude text formatting and inclusion of
figures, so a document such as ripe-500 can not be converted into plain
text without loss of information.

I do not like the idea of using PDF for documents like ripe-500 though.
PDFs are hard to collaborate on; standard tools like diff cannot
meaningfully represent the differences between two versions of a
document. I would prefer something like HTML, where you could download
an archive file containing the main policy text as a HTML file and any
figure or image files referred to by it.

I'd also suggest that a conventional 80-character line length limit
would be used in the source format, as limiting the line length makes
reading diffs easier. That doesn't mean the published document's web
page cannot be reformatted to have longer lines of course (something
that would happen automatically with HTML).

-- 
Tore Anderson