Documentation Driven Development

Last week I went to Heavybit Dev Guild and learned about designing for developer experience (DX). This was the first time I had heard of the term DX used, but of course it makes perfect sense. All of the Heavybit companies (including CircleCI) are focused around creating developer tools. Naturally when you are creating tools for developers the types of things that make those tools useful and a joy to use are very different than when your primary audience is the mass consumer market.

All of the talks were great, and I am pretty sure that they will be posting videos of the talks here so keep an eye out for that. Three things really stood out to me:

First, during the opening remarks, Jesse Robins talked about how developer tooling changes the culture of an organization. If you want to change the culture of an organization then its not enough to just build a product, you have to also build a movement.

Second, during a Product Discovery Panel, Patrick Malatack mentioned that before Twilio writes a single line of code they write the docs first. We have heard of Test Driven DevelopmentBehavior Driven Development, and * Driven Development, but this is the first that I have heard about “Documentation Driven Development”. This is such an amazing idea that I would love to dig deeper into. So often documentation is just an afterthought. Good documentation (especially when you are working on a FOSS project that does not have “official support”) can make or break your platform. DDD makes a lot of sense when your product is primarily an API like Twilio, I suppose it could fall apart for other types of products. In any case, it is critical to periodically step into the shoes of a brand new user and go through your documentation.

From a support perspective, there is nothing more annoying than getting 100 questions from a user who clearly didn’t even bother to read your documentation. But from a users perspective, there is nothing more annoying than reading documentation and finding out that the person that wrote it has not looked at it in three years because nothing works. In short, if you want your users to RTFM, make sure the FM is worth reading.

Lastly, during a founders panel that discussed building vibrant developer communities. Matt Debergalis talked about how when they first started Meteor they tried to follow an Apple model when it came to product design decisions. He stated that:

Apple Model does not work in FOSS, since you don’t control your own product. People are gonna show up with not just feedback, but also code.

Overall, this was a great event. I am looking forward to the next one. Huge thanks to HeavyBit for making this happen.

debian, linux

Installing LXQt on Debian Testing


Ever since I read about the merger of LXDE and Razor-Qt into the LXQtproject I have been patiently waiting for it to be available on Debian. Razor-QT was a beautiful, clean, and fast desktop environment, and LXDE has always been my go to choice for low power hardware. I have tried installing LXQt a few times in the past running sid, but the experience was never as good as I would have liked it to be. This weekend I finally got a chance to install it with the latest version of Debian Testing, and I am excited to announce that its wonderful. I have been growing disillusioned with the state of the Linux Desktop for a while now. Back in the GNOME2 days I could always count on my Linux Desktop being as fast, responsive, and sane. But GNOME3, Unity, and even KDE 5 feel clunky and slow (especially in a Virtual Machine). I want my Desktop Environment to get out of my way and let me do my work, and LXQt lets me do just that.


Installation is pretty straight forward. I would recommend starting fresh, and install Debian Testing “standard” (i.e. no Desktop Environment at all). Once you have gone through the regular installation process, you should find yourself in a shell. Install xorg and lxqt with the following commands:

apt update
apt install xorg lxqt -y

This may take a while, but once this process is complete you can reboot and you will find yourself in a beautiful, modern, fast, and productive desktop environment.

Post Installation

You will find yourself in a pretty bare bones environment. I would suggest installing firefox, emacs (or whatever other text editor you like), a mail client (check out Sylpheed), Dropbox, and LibreOffice.

Parting Thoughts

My absolute favorite part of LXQt so far is that it comes with the awesome qterminal application which has simple horizontal and vertical splitting similar to iTerm2. This is the first time that I have been exposed to this emulator and I love it so far. Kudos to the LXQt team for an amazing release, and thank you to the Debian maintainers for packaging this up nicely. I am looking forward to continue to see LXQt improve. If you are looking for a fast, traditional desktop experience, I would highly recommend giving LXQt a try.

No Justice, No Peace

I left work today and was amazed at the site of hundreds of people marching down Market St. People of all ages, races, genders, ethnicities, and sexual orientations. Angry, fed up, determined to have their voices heard. It was a moving sight to say the least. Of course my phone was dead at the time, so instead of photos, I will describe what I witnessed.

As they made their way up the street, they said many things.

No Justice, No Peace, No Racist, Police. The whole damn system is broken as hell. Black Lives Matter

People on the side walk watched, armed with their smart phone cameras. Some took photos and videos, some look confused, some look scared. Market St. at this time of day on a Friday is full of tourists waiting in the long lines to get onto the Cable Car. Everyone stopped what they were doing to watch the demonstration unfold.

The most inspiring part was that some joined in. People who were not planning on being a part of this were moved to walk side by side and make their voices heard too.

There was a guy playing his saxaphone in front of Westfield mall. Even with all of the noise, he kept on playing. I didn’t hear a single note that he played, but his dedication to his craft inspired me so I threw $5 into his sax case.

Like many people, I am shocked, saddened, even disgusted with the current state of affairs in this country. I am glad we live in a place where we are legally allowed to come together and tell the powers that be that the system is fucked. I hope someone is listening. When non-violent demonstrations fail to be recognized, they tend to turn violent. In some cities this has already happened.

We must come together. Young and old, gay and straight, christian and muslim, black and white. We must come together and make this world a place where we can all live in peace. There is no other alternative.


I made my way over to City Hall after my phone charged for a bit and took a couple of photos. Many people spoke, and I stood there and listened. The most profound thing that I heard, was the end of one woman’s speech:

I can no longer accept the things I cannot change. I must change the things that I cannot accept.

In addition to the quote, one thing that someone said that cannot be more true is that this is not about coming out for one night to protest. This is about what we, as a community and as individuals do tomorrow, and the next day. Spread the word, share these photos, keep the conversation going until we find a solution.


Using org-mode with Jekyll


Since my journey into Google Docs’s Hell I have been getting more reacquainted with org-mode for other purposes as well. Traditionally, I have been writing this blog using Markdown and publishing it with Jekyll. I love Markdown, and while it is fine for most cases, but what better way to gain more experience with org-mode than to blog with it! The best tutorial that I have found so far is this one from the org mode web site: Using org to Blog with Jekyll. One “gotcha” that I have ran into so far, is everything breaking if I include a table of contents (which happens by default when you export to HTML). The simplest solution for this is to add the following to the top of your org flavored file.

#+OPTIONS: toc:nil

This allows the front-matter to be exported properly. I am also choosing not to include section numbering for my posts. So the complete front-matter for this post looks like this:

#+OPTIONS: toc:nil num:nil
layout: post
title: "Using org-mode with Jekyll"
permalink: /:title/
tags: hacking


My jekyll blog project looks like this:

;; File ~/.emacs.d/customizations/setup-org.el

;; ...

;; Projects

;; Blog
(setq org-publish-project-alist
         ;; Path to org files.
         :base-directory "~/git/"
         :base-extension "org"

         ;; Path to Jekyll Posts
         :publishing-directory "~/git/"
         :recursive t
         :publishing-function org-html-publish-to-html
         :headline-levels 4
         :html-extension "html"
         :body-only t


My current workflow looks something like this:

  1. Add a new file to git/$DATE-$
  2. Add the front matter shown above
  3. Blog my heart out
  4. Check my spelling with ispell
  5. Publish the org file with C-c C-e P p , this moves the file from git/ to /git/$DATE-$TITLE.html
  6. Build and Deploy my site with my Rakefilerake deploy.


There is definitely some room for improvement here such as macros for dumping in the front-matter, easier deployment, and more automation. I plan on seeing what I can do to make this process a bit smoother for me and update this post when I do.

Org Mode To Google Docs and Beyond


The other day I was attempting to make a structured document. It has been years since I have done this and I have forgotten what a pain in the ass most word processing software is. When I used to work for a .NET enterprise health care company, I would often find myself in “Word Hell” with no hope of ever returning. This time I found myself in a new place, Google Docs Hell. It’s similar to Word hell, but runs in the cloud. All that I was really trying to do was create a document with numbered headings and a simple table of contents that links to said headings. I suppose that this is too much to ask for because although I was able to get my headings to work more or less, as soon as I tried to add content under the headings Google Docs decided that I really wanted random page breaks after every heading. After banging my head against the wall for a few minutes, with no clue on how to even begin to troubleshoot this issue, I busted out my trusty old friend Emacs. Emacs Org Mode has never failed me. I remember back in college when I needed to add code snippets or non-trivial equations into a document that I was working on, and this was a seemingly impossible task in any word processor that I found. Org Mode is well suited for this type of task since it is a plain text system, and in my experience plain text combined with a sane “compiler” is the only way to truly have WYSIWYG. Other native WYSIWYG editors like Word, Pages, Google Docs, and even LibreOffice are very complex pieces of software, so figuring out why a random page break is being inserted in the middle of an ordered list is only possible if you have no value for your time.

Enabling Org Mode Exporting to ODT

Recent versions of Org Mode are capable of exporting directory to ODT format, and it works more or less very well, but the documentation is not the greatest. For instance, this page says:

The ODT exporter relies on the zip program to create the final output. Check the availability of this program before proceeding further.

But it does not really tell you what zip really is. I am assuming its whatever is in my $PATH on OS X, but I can’t really be too sure.

Copyright (c) 1990-2008 Info-ZIP - Type 'zip "-L"' for software license.
Zip 3.0 (July 5th 2008). Usage:

Also, no where in the docs does it tell you how to enable ODT exporting. In order to be able to export to ODT like you would export to any other format using the C-c C-e export menu, you need to explicitly enable ox-odt somewhere in your org-mode configuration file. Check out my .emacs.d repo for an example, but essentially adding this somewhere in your startup scripts should do the trick:

;; Load ODT backend to allow for exporting to open document format.
(require 'ox-odt)

Exporting to ODT

With all of that out of the way, we are free to start exporting things to ODT. Fire up org mode and write your document to your hearts content. When you are finished you can export it to ODT with C-c C-e o o. Opening up this file in LibreOffice or OpenOffice should show you a really nice representation of whatever you just wrote. The best part about this method is that you get a table of contents, and section numbering for free. In addition, you do not have to keep track of the numbers yourself, if you need to move stuff around or add new sections then org mode export will automatically update the numbering for you. Besides being able to export to ODT, org-mode also supports exporting to about a dozen other formats. If you have LaTeX and pandoc installed then the sky is truly the limit.

Uploading to Google Docs

While the editing capabilities of Google Docs are suspect, it is difficult to argue that its not one of the best tools for collaborating with your team. Unless you are writing a manifesto in a cabin, you likely want to share your latest creation with your team for feedback. I would not recommend uploading the ODT directly to Google Docs, since the formatting can get a bit thrown off. Instead I suggest exporting the file from LibreOffice into .doc or .docx and then uploading that. From my preliminary experiments this seemed to work the best.


If you are writing a complex structured document, especially one with formulas or code snippets. You will be hard pressed to find a better environment than Emacs with org-mode. Enabling the ODT export in org-mode makes it fairly simple to upload your documents to Google Docs and be able to collaborate with your team.