**| documented.

Keeping documentation for systems up-to-date can be a struggle for many projects–most developers tend to avoid writing any documentation because the solving the problem in almost always far more interesting than explaining it to someone else.  There have been systems that connect the code with developer-oriented documentation such as Godoc, Sphinx, JSDoc, docco or YARD according to whatever programming language or platform you program in, but not so many systems that generate end-user documentation directly from the source code. This is my concept of how to do it within the source for end-user documentation that am I calling “**| documented.”  This is a weird name so it stands out, but it also happens to also use the syntax of the system for the system, so that’s kind of recursive and… geeky. Ok, neveryoumind that, let’s dive into what it does and why.

Finding the minimum syntax for **|d.  should not be too hard, we want to be lazy about this. A simple state and line-oriented protocol that fits within multi-line commentary. The tools that we’ll make to process the documentation will ignore single-line comments, because mostly these are the actual comments between developers or used for developers’ documentation which is of course not the target audience of end-user documentation.

In this first revision of the idea, let’s just concentrate on these requirements:

  1. Documentation and source-code have to be close together, or they will drive apart. If the source doesn’t do what the documentation says then one or the other has to be fixed.
  2. Support different markup languages like Markdown or SILE or even TeX.
  3. Multiple human languages are supported via their 2-character ISO language codes.
  4. Common text between all languages must be explicitly marked so that it can be shared–an application of the DRY (don’t repeat yourself) principle.
  5. Don’t make the author write more than they should have to write to denote what is end-user documentation vs. the rest of the source code.
  6. Be visually appealing in source-form.

We’re not even going to write code for this yet, but instead imagine the end-in-mind, it shouldn’t matter which tool grinds out the documentation from these cues.

Here’s an example of one format with English, German and Spanish texts in Markdown:

en| # Heading
  | English documentation continues for as long as the pipes are 
  | unbroken. 
de| # Überschrift
  | Die deutsche Dokumentation setzt sich fort, solange 
  | die Pfeife ungebrochen ist.
es| # Título
  | La documentación en español continúa mientras el tubo no 
  | esté roto.
en| Documentation that is common to all languages, such
  | as data or other information can be shared with ** sections.
  | The paragraph break above will be in all languages as well
  | as the list of data below:
de| Dokumentation, die allen Sprachen gemeinsam ist
  | Aufrechtzuerhalten Da Daten oder andere Informationen mit ** Abschnitten geteilt werden können.
  | Aufrechtzuerhalten Der Absatz oben wird auch in allen Sprachen sein
  | Aufrechtzuerhalten Als die Liste der Daten unten:
es| Documentación común a todos los idiomas,
  | Ya que los datos u otra información se pueden compartir con las secciones **.
  | La pausa de párrafo arriba será en todos los idiomas también
  | Como la lista de datos a continuación:
  | * 38,934 kg
  | * 34 kg
  | * 12 kg

And here is another brief text in LaTeX markup:

en| \chapter{The Big Chapter}
  | It was the worst of times, it was the best of times...
de| \chapter{Das große Kapitel}
  | Es war die schlimmste mal, es war die schönsten mal ...
es| \chapter{El Gran Capítulo}
  | Fue el peor de los tiempos, fue el mejor de los tiempos ...

Specifying the Markup Format with <|

I don’t want to force a markup format on anyone, as there are always formats more suited for different documents all the time.

Specifying the Audience or Document with @|

This is intended for separating the stream of documentation into different documents for different audiences. Maybe you want something for press-relations, something for the impatient new-user and something for the developer. Examples:




Locating the Fragment with ^|

Where something goes in a document very often has little or no relationship to where it may be written about in the source code.

Switching to a Language with ISO Language Codes

ISO codes are well-known and stable identifiers for different human languages.




Indicating All Languages with **|

Information shared across all languages, such as tables of numbers or other bits of syntax that transcends all language can be indicated with a “double star pipe” prefix.

This might be all we need for now, but if anyone who has had serious multi-language-multi-document systems experience with this kind of inside-out “literate documenting” (as opposed to “literate programming”) has any other ideas, I’d like to hear about them.