Stream: ideas

Topic: Editor POC + Living Documentatio

Matthias Devlamynck (Dec 02 2021 at 08:12):

I've been inspired lately by talks on living documentation (weirdly enough I only found talks in french). The TLDR is the following:

• Keep one source of truth were possible
• Generate other convenient documentation formats from that source of truth (generated code architecture directly from code source, or database schema from existing database)
• When we can't keep only one source of truth prevent them from diverging with an automatic detection (think code as a source of truth and tests as an other, both specify software behavior, running the tests checks for consistency, BDD with Gerkhin is a classic example of docs that also can be used as tests)

When working on a structural editor in my spare time I wanted to experiment with different ways of interacting with it without spending to much time implementing it (I wanted fast feedback, and also I wanted to be able to keep experiment). My idea was to document what the interactions I wanted and have a fake "editor" read that doc and play the scenario (automatically or interactively). The "editor" would be useless for actual editing, but it could demo features I had in mind (and maybe generate gif) and more importantly let met actually test how the feature felt when actually interacting with the "editor".

And it being documentation I can see it become part of the user manual / guide of the editor (It could more or less become the equivalent of the vim docs, augmented with demo gifs!)

It could also become functional tests for the real editor as it would contain interaction scenario, an automated tool could check the consistency of the doc against the real implementation.

For now it only a more or less crazy idea, I'm not sure how well it would work in practice. I can come up with a very simple demo of this idea if anyone is interested.

Anton (Dec 02 2021 at 09:32):

I like this a lot and am definitely interested in a demo!

Matthias Devlamynck (Dec 02 2021 at 11:36):

I'll try to build it this weekend :)

Anton (Dec 02 2021 at 13:02):

:+1: No rush :)

Matthias Devlamynck (Dec 02 2021 at 13:13):

It's fine I have my old experiments lying around :)

Zeljko Nesic (Dec 02 2021 at 15:48):

Please do! I am interested in seeing the demo too :)

Take your time, no dead lines. :)

Matthias Devlamynck (Dec 05 2021 at 11:20):

Here it is: https://github.com/mdevlamynck/living-documentation-editor-poc
Needs a lot of work before it can start to be actually useful but at least it shows the idea.

Anton (Dec 06 2021 at 10:18):

I love it :) the interactivity makes it a great simulation of the final product. I have some tasks to finish up but after that I'll get in touch to discuss how to integrate this approach with the editor code.

Matthias Devlamynck (Dec 06 2021 at 11:07):

Nice to see you like it :)

Zeljko Nesic (Dec 06 2021 at 12:13):

I think it doesn't work on my Mac

When I run cargo run -- scenarios/writing_clamp_function_roc.md

I get just this:
Screenshot-2021-12-06-at-12.12.44.png

Zeljko Nesic (Dec 06 2021 at 12:16):

Even C-c doesnt work, nor q ...
Let me try it on Linux machine

Matthias Devlamynck (Dec 06 2021 at 12:39):

@Zeljko Nesic it seems to be working. At the moment it's very basic, it just reads the markdown file you give it and extracts pairs of screen and key (take a look at the markdown file, it contains code blocs (3 backticks) for the screen and inline code (1 backtick) for the key). It then show the first screen (which is simply the [_] in the screenshot) and only show the second screen when you press the right key (the one next to the screen in the markdown).

It's really not obvious what it does, I tried to explain a bit in the README. An obvious improvement is to display the key the demo expects from you.

Matthias Devlamynck (Dec 06 2021 at 12:44):

If it makes things clearer the expected key sequence to run scenarios/writing_clamp_function_roc.md is clamp \v low high v |max low |min high (including the spaces).

Zeljko Nesic (Dec 06 2021 at 15:14):

YES!

Zeljko Nesic (Dec 06 2021 at 15:16):

This is what my editor prototype was trying to achieve :)

Zeljko Nesic (Dec 06 2021 at 15:17):

Basically driving you trough right nodes of the code

Zeljko Nesic (Dec 06 2021 at 15:18):

Only thing I am not sure what is "Living Documentation" supposed to be. but none the less great stuff! :)

Zeljko Nesic (Dec 06 2021 at 15:20):

Also great way to present interactions

Matthias Devlamynck (Dec 06 2021 at 15:37):

The core idea of living doc is to treat your doc not as a static (dead) thing, but try to extract data where it lives (either in a text doc itself, or in source code, or wherever it lives) and generate docs and tools from that data. So for example instead of maintaining a doc describing the architecture of an app, it should be generated from the code itself.

The usage of living doc I'm trying do here is having a doc describing the UX of the editor and generating a demo from that. It allows me to quickly try out different designs to see if they feel nice to use.

The concept doesn't seem to be widely known in the industry (and is a bit hard to explain). I'm not sure if this is just a matter of time before it takes off or if in practice it doesn't work that well.

Anton (Dec 08 2021 at 16:47):

I haven't forgotten about this @Matthias Devlamynck but I was not aniticpating my tasks becoming multi-day tasks :p I hope to be done by saturday evening at the latest.

Matthias Devlamynck (Dec 08 2021 at 16:57):

@Anton Don't worry take your time :) I've been busy trying to figure out how to grow the idea into something usable without turning it into something to big and complex.

Last updated: Jun 16 2026 at 16:19 UTC