What is Plannr about ?

I would describe Plannr as a combination of private Twitter + Evernote.

Plannr started as a frustration with the current note taking tools. Over the years I have tried

  1. Textfiles, todo.txt

  2. Tiddlywiki

  3. Evernote / apple notes

  4. Trello

I used evernote for the longest time but I also found myself increasingly using twitter for bookmarks and journalling. After my initial frustrations, I built my own version of vimwiki and then a script that would append entries in reverse. Plannr is the next iteration of this idea. Some other inspirations include the .plan files and engineering logbooks.

Plannr also has a public sharing option, which together with RSS makes it simpler and less noisier way to microblog. Did I mention it has markdown support ? Together with checklists and a heatmap, Plannr makes it easy log bookmarks, ideas and status updates for your projects.

You can see Plannr’s updates in this public notebook.

This document is also a literate program

While the first version of Plannr used svelte and Mongodb, I had a use-case for custom javascript that wouldn’t work with a extra compile step. I decided to fallback on good old ejs templates - at which point I began to wonder, how different can I go ? How many assumptions of web development can I drop ?

Here are the assumptions I experimented with,

  1. In the frontend I decided to drop AJAX completely and go with websockets.

  2. I developed a simple database ~ 1 json file per user before I moved onto 1 sqlite database per user.

  3. The initial app was an Electron App, I dropped it to move to the Web.

  4. I moved from nodejs in the backend to hylang, a lisp that I had been using for small scripts. I dropped the parens with an external filter to support ruby-like s-expressions, which I dub as r-expressions.

After the backend reached its final stages, I found the codebase difficult to explore and adding features annoying; unlike the initial phases of the project. A typical codebase will have tests, frontend and backend located in different files. Navigating them is a pain and has a lot of context switching involved. I started using a vim hyperlink plugin to link different sections of code together. Although initially useful the links themselves were getting out of hand and then I remembered that Literate Programming had cross-referencing links too.

Literate programming has had a profound effect on the codebase. The literate code tool - wheel - which uses sphinx and cog is available here along with my notes and bookmarks on literate programming.

Here are notes on the effect of literate programming on the codebase,

  1. I can read the code in the browser, casually. Spotting bugs and repetitive code is easier.

  2. TODO’s and FIXME’s make it easy to start from where you left off. This is less taxing on the memory.

  3. Backend, tests and the frontend templates are in one place. By far my favorite of all. This makes files and folders irrelevant. Files are for the compiler.

  4. No more commit messages.

  5. No more creating unnecessary files for modularising

  6. Big functions are not a problem anymore because it can be divided into sections, keeping code screenful. Code readability is dramatically improved, which is what 90% of programming is about.

  7. No need to divide code into functions for comprehension. A function is created if its reusable. A snippet which is a smaller unit of code reuse is also available. Literate programming can enable ad-hoc text generation using templates.

  8. No more source banners.

  9. Each chapter is a new feature. This is much better way to think about code organisation than as files, functions and folders.

  10. You can drop webpack for minification. The literate program acts as a glue connecting multiple build tools together. Heck if you want, spellcheck your code because you have pipes.

  11. Because of cog, even the documentation can be divided into sections and passed through external tools.

  12. Single file for everything that means no need for grep or complex refactoring tools.

As a literary genre - most literate programs fall under the “how things work” style. While that is useful for complex algorithms its not useful for normal everyday code. I assume some form of code literacy. I believe a history book like approach will be more useful for everyday programs.

Bear in mind that the source code here is highly experimental and is also used to test the limits of my literal tool! The decisions and reasoning for some features is explored in the subsequent chapters. The entire source code is in the code walkthrough chapter where you can see the backend, tests, templates and javascript for each feature in a sub-chapter.