Visualising content

I wrote a post back in July about the need to improve the tools that allow us to work with text. Specifically, I said:

The solution is not building tools around Word Processors, but removing word processors from the upstream work flow, and using them, if at all, for cleaning up and appearance for output reports.

Whether or not complete removal is practical is an open question. In any case, I think there are definitely benefits in upstream tools, for our ability to represent information, present with it, compress information for teaching, and also to help with sequencing it.

With this in mind, here is my prototype (Project ‘Shelf’) that I’m using to experiment with the utility of such a thing. The source code is here: https://github.com/craigduncanlab/shelf

This is a 2D grid-based text editor that allows you to hide away the details, move tiles around and just see your document (or set of ‘notes’) in a 2D layout.

This example is a set of clauses from a contract.

Each of those tiles hides away complete clauses, links to images, notes, or links to other files you have on your computer. The content could be anything :

  • a set of topics for a presentation
  • some notes for useful websites
  • some legal concepts where you want to hide away case references or definitions.

The list can go on. You could use this as a presentation tool where the tiles are the outline of your presentation, and then you open up a web link or another document if you want to.

One of those benefits is that to set all this up requires nothing more than a raw text (.md) file. The underlying file for this graphical UI includes a few custom annotations, but it is compatible with ordinary markdown. The program also saves your output to .docx, silently. This is automatically updated to match the order of the tiles in the 2D text grid, without you having to do anything.

The .docx is silently created (automatically) for you.

The row and columns in the UI are deliberately left undefined, for now. For example, my background notes tile is position below the other content, so that I can see it is different.

When that is selected, and I press space, I get to see ‘the main text inside’ my block.

If I want to edit, I select the tile and then press “Enter” instead of space and I can edit my text:

One of the interesting implications of moving to this format is that it forces you to reconsider you commitment to drafting conventions, like explicit numbering and cross-referencing. Let’s say I want each clause to be independent. Do I really need that comment that says “under clause 14.3”? Or can I just say “under this Clause” or “under the Clause titled “Indemnity”, so that it still make sense regardless of the order in which I am drafting? I think there’s some merit in moving to relative, qualitative references, even if the final output has numbered clauses for human readers.

Another thing that I’ve included is the ability to convert from the editor fields and text to an HTML preview for these pop-up windows and the editor.

This is how the editor looks when working on it:

You can edit in a markdown format on the left, and see the preview on the right.

This previews what it will look like in docx, but in .docx there will be numbering too. At the moment this has two levels – the clause heading gets to be the equivalent of “Heading 1” and any text with double hash (“##”) at the start will be Heading 2. This can be extended to more levels.

Getting back to the .docx option (for those who want to ‘get back’ or ‘render’ to Word), the program will create .docx based on the left to right order of tiles, returning to the tile at the start of the next line. The document and tile layout shown above will produce this:

An auto-generated .docx.

The actual file that this program is working with is still very simple and easy to edit directly, if you wanted to. It’s not locked up in some complex database or proprietary format.

The source file

Now I could create a new source document for my 2D tile editor just by creating this in a text file:

and then opening it up from the app menu…

To produce this for editing/moving:

And when I save the above file in the UI, it will silently create this .docx for me:

If I move the tiles around, and resave, both the raw text order and the docx files are modified to reflect the new order of the tiles.

The ‘feel’ of the interface is another important thing. There are a few shortcuts in the prototype (and the list will be increased, as will the functions). So you can nudge all the tiles to the right of the selected tile ‘right’ by pressing CMD-R, and nudge them left by pressing CMD-E. You can delete a tile by pressing ‘delete’, or make a new tile near your selected tile by pressing CMD-N.

You can drag and drop tiles using the mouse. You can do this without affecting order (e.g. space out your tiles), or you can do it to change the order of the document itself.

The ‘feel’ is probably best illustrated by a short video, which I’ll get to soon.