Coding /

Developing in Docpad

I’ve started developing in Docpad because I love lo-fi text-only documentation. This CMS uses folder structure and tags for site hierarchy and is very flexible. The MarkDown is transpiled into html and I can use a variety of templating languages for the layout components.

I’m going under the assumption that this will all provide maximal flexibility while I am actively creating content.

Lo-fi Conceptual Representations

I write a lot of notes every single day in MarkDown and yaml. I am continuously organizing data, some of which is verbose tagged text, and some of which is tabular or hierarchical. I feel like I am constantly running out of elbow-room in standard documentation tools such as Confluence, Evernote, and OneNote. They also kind of box you in to their silo of information, even though they allow rudimentary export functions.

I have been keeping the lions share of my notes in MarkDown, using folder structures to hold all variety of document types, with VSCode as my text editor/organizer, and committing to GitLab, BitBucket and GitHub.

VSCode for all ad-hoc notes and record-keeping is ideal, even for UML for which I can use PlantUML to render my markup.

I decided a while ago that text notes are the fastest way for me to store spontaneous notes, and with practice my skills and capabilities have improved. It is amazing what happens when you narrow down your output to lo-fi text, instead of trying to open drawing programs on the spot and paint out your ideas, or other hi-fi schemes. I like making notes first, about whatever it is I want to create.

Notes can be very specific, for instance specifying specific colors or quantities or named things. Once you have the notes, maybe including bulleted lists or other structural data, you can render the concepts out in the appropriate tool. The important thing is to be able to express and articulate the most elaborate ideas in the first available, most broad-range, tool, which will always be words.

The Visual Idiom ReWrite

I am reminded of Microsoft’s decade-long foray into “visual programming”. The whole tool-set was built on the premise that people wanted to create things visually, and that that method was more “creative”. Apple had a more impressive visual UI. The Microsoft OS still started up with text scripts running while the OS booted. They made a valiant effort to move further into the visual idiom, but at around the same time period, Apple was moving in the other direction. Now it is the Apple users who are more likely to have a command line terminal window open to run the verbal commands they want to execute.

The entire computing industry has moved toward visual-only interfaces repeatedly over the last several decades, for instance in data-transmission schemes. Now it is all JSON and YAML at some point. People want words to help them understand pictures.


  1. Choosing Hugo Over DocPad
  2. Developing in Docpad