**| 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:

/*
 @|user
 <|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:

/*
 @|user
 ^|1.0
 <|latex
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:

@|press

@|developer

@|user

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.

en|

de|

es|

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.

 

 

Advertisements

The less secure a man is, the more likely he is to have extreme prejudice. –Clint Eastwood

Cord-cutting technology

My antennas don’t look like these, because they’re for UHF for OTA HDTV [Which I only use in weather emergencies because broadcast TV is singularly awful…], but this is still an interesting read:

If you happened to look up during a drive down a suburban street in the US anytime during the 60s or 70s, you’ll no doubt have noticed a forest of TV antennas. When over-the-air TV was the only option, people went to great lengths to haul in signals, with antennas of sometimes massive proportions flying…

via On Point: The Yagi Antenna — Hackaday

Selected Process Round-up

Ever feel like you’re swimming upstream in a tsunami when you’re a developer/systems administrator/entrepreneur?

Here are some life-lines:

  • Lean Inception” (How to decide what to build and when to do parts of it.)
  • Kanban in Action” (How to communicate with others about when things are being done and the results.)
  • Continuous Delivery” (How to reproducibly create systems with higher quality, reliability and less stress.)

It’s just three things, but perhaps, only one is what you need. By far the biggest frog you’ll eat here is continuous delivery.

Dropping Vivaldi

Good defaults make programs easy. Bad defaults aggravate and waste your time. Spending your time fiddling with those defaults = more wasted time. Because Vivaldi’s keyboard shortcuts are too often interfering with keyboard shortcuts of other websites, I’m going to have to drop it as a web browser.

Maybe I’ll try it again in the future if they implement suites of keyboard-configurations so you can choose “Chromium” compatible or “Firefox” compatible. Trying to fix these as you experience the paper cuts in day-to-day use is not worth the trouble.

FastMail is still awesome though.  You can nearly manipulate anything in FastMail with the keyboard.

A Microwavable Notebook?

Yes. They exist. Except for the dotted grid pattern that enables them to be digitized inputs, you can only nuke them five times.  From my own personal experience, you don’t need the digitization—99% of what you write on paper is thought-junk you need to perform to work out the valuable ideas.

Label and date every page at the top. Multiple pages on same date get serialized.

The paper + recycling bin wins, no microwave required. $27 for two notebooks becomes $27 for about 1300 sheets of reinforced filler paper out of which you’ll make 13 pages of “gold.”  For two microwavable notebooks, you can only grind your mind’s work into 800 sheets—none of which you’ll tear out and archive.