Ryan Daigle

iPad Pro Publishing: From Ulysses to Jekyll with One Tap

2018-05-04T00:00:00+00:00

With iOS 11, the iPad Pro made a tremendous leap in capability. The hardware is fantastic, multi-tasking is no longer a bolted on step-child, and keyboard-driven workflows are becoming more common.

As I mainly use my iPad for writing-based workflows, it was pretty important for me to be able to efficiently write, and publish, from my iPad. My blog is based on Github Pages, so it’s backed by a git repo and uses the Jekyll static site framework. On a laptop that’s easy to setup, but isn’t quite as seamless on the iPad.

Thankfully, Workflow (and the excellent Working Copy) come to the rescue. From my writing app (Ulysses) I can publish with one button. Rather than describe the results, I’ll just post a video of me publishing this very post:

💥💥

I’ve published this workflow in the Workflow Gallery if you want to give it a try yourself. I’ve done my best to extract out all the Ryan-specific details but, let’s be honest, that’s a stink that you can never really escape.

Setup

Here are the basic steps to get this workflow installed on your iPad. This assumes you have an existing Github Pages site already setup in Github using Jekyll, and Workflow installed on your iPad.

Working Copy

Install the git client Working Copy on your iPad and be sure to enable URL callbacks from the application settings (in the app).

Write down/copy the URL key, which you will need when setting up the workflow.

Also be sure to clone the Github Repo of your blog (e.g., yourname.github.io) in Working Copy so you have the source on your iPad.

Workflow

Download my “Publish to Jekyll” workflow from the gallery. It will ask you a few questions to configure the integration, in this order…

First is your Working Copy x-callback URL key (see above for getting that):

Next is the name of your blog’s github repo:

Next is the URL to your blog’s site. If you have any extra path info to get to your blog posts, be sure to include it (but not the trailing /):

Finally, it will ask you for the author name you use when publishing your posts (this gets added to the “front matter” for each post in Jekyll):

Once the workflow is downloaded and configured, it will appear in the share extension for any text document.

Publishing

I use Ulysses for all my long-form writing, and it’s a great place to publish from. Once you have an article you’re ready to publish, you can invoke the workflow right from the action button. The only nuance is you have to be sure you’re in Text/Markdown preview mode (vs. just sharing from the standard writing view). Here’s what that looks like:

Once you’re viewing the text form of your article in Ulysses, you can trigger the “Publish to Jekyll” workflow and you’ll be off to the races!

The only thing the workflow will ask for during publishing is a list of tags for your post (used by my Jekyll setup - yours may not). Enter a comma-delimited list of tags if you use them, or leave the field blank if you don’t (or just remove that step from the workflow if you’re comfortable doing so).

If successful, the workflow should complete and open your new post URL (which might not be live yet since it takes Github anywhere from a few seconds to minutes to actually publish your post).

If it fails, the workflow will abort with (hopefully) an error message. Most of the time the error will have occurred in Working Copy (e.g., there’s a merge conflict, you don’t have the latest version on your iPad etc…).

Publishing on an iPad may never be as seamless as a laptop - but it’s pretty impressive what you can accomplish by chaining a few well-implemented apps together.

Happy publishing!

My iPad Pro Experiment

2018-02-09T00:00:00+00:00

I’ve been intrigued with the iPad Pro as a laptop replacement for awhile now. The battery life, the constant connectivity, the rock solid and sand-boxed OS, the portability - these are things that really appeal to me. After reading one too many “how I switched to the iPad Pro” blog posts from fellow tech-types I was convinced. It was time for me to take the plunge and give the iPad Pro a run as my laptop replacement.

I scurried off to the Apple Store like a giddy school girl and walked out with a 12.9” iPad Pro and a Smart Keyboard. The world was my oyster. The sky was bright blue, the flowers were in bloom. It smelled like optimism and Panera (there was a Panera right by the mall exit).

But that experiment turned out to be a failure.

Not one week in, it was clear the iPad Pro could not be my laptop replacement. What happened?

Initial expectations

When I first got the iPad Pro, I envisioned it being the only computer I would need, a true laptop replacement. I would live a life of complete freedom (I have a child), roaming an exotic European city (I live in the middle of North Carolina), settling into a quaint café (I’m not really a coffee person), confidently tying up my man bun (I’ve never had long hair) and working away on my creative endeavors (I have a first-grade level of creativity, at most) with the iPad.

Ahhhh… perfection.

In reality, even my rather conventional needs were left unrequited. And all because of one weak link.

Hardware

The iPad Pro hardware is fantastic. Amazing screen, great sound, high build quality, great form factor. 😚 Mmmwaaaa (or whatever sound one makes when holding their fingers to their mouth and kissing).

The Smart Keyboard is actually quite good too. I had no issues writing for long periods of time on it. Just enough key-travel to satisfy my stubby nubs and the surface material is lightweight in feel, but durable with just the right texture. And the way it conveniently folds up as a cover for ultimate portability - superb.

Could it have some extra quick-function keys like a home key, Siri key? Probably. But overall it’s a great little package and I can definitely recommend the Smart Keyboard.

Operating system

iOS 11 (the current release as of this writing) is pretty great. It’s a really pragmatic combination of iOS’s traditional sandboxed app paradigm paired with some convenient multi-tasking workflows (think split-view, drag-n-drop, persistent menubar, etc…). It’s rock solid stable and you find yourself pulling out your phone less because all those mobile-centric workflows (Authy, iMessages, Twitter, etc…) are right at your fingertips now.

Is control center a bit of a mess on the iPad? Yeah, it’s definitely not as convenient as on the iPhone. Same goes for Notification Center and whatever you call that screen over there to the left where widgets go to die. But as an overall experience, iOS on the iPad is pretty swell.

The apps

The apps. Oh, the apps. This is where it starts to be a mixed bag. Are there some standout apps on the iPad? Absolutely! iOS is still the best app ecosystem by a long shot. However, the iPad-specific app ecosystem within isn’t nearly as robust.

Most iPad apps, by now, have been upgraded to comfortably live on the larger dimensions of the iPad. But most still assume a touch-first interaction model. I believe is a mistake for the iPad Pro.

For most folks the Pro will pretty much live in landscape mode paired with a keyboard. In that configuration, having to always reach up to find a touch-target, or execute the finger choreography required for some gestures, is a very jarring experience. It breaks the hands-on-keyboard posture and feels excessive given the frequency some apps make you tap on them.

I’ve read enough peoples’ write-ups to know this isn’t a universal opinion. Some people don’t mind typing, reaching up to tap or swipe, then back down to continue typing. For me, though, this type of break is supremely frustrating. I’m a diva, deal with it 💁🏻‍♂️

And even if you’re not a fragile snowflake like me, you will probably find several apps you rely on that are frustratingly unoptimized for a landscape-dominant setup. Broken web views, weird rendering quirks, all-around bad app citizens - these are common occurrences on the iPad.

At the end of the day the reality is iPad apps are rarely any company’s first priority. They’re probably more inline with desktop apps on the development pecking order of: Mobile (iOS & Android) > Web app > Desktop/iPad. With these priorities, is it any wonder the app experience on the iPad is what betrays what is otherwise a compelling experience?

And so … here is where our story ends. Me, frustrated by one too many poor app experiences (I’m looking at you Dropbox Paper) and disillusioned from my utopian vision.

The iPad Pro ecosystem just isn’t ready yet.

Round Two

AND YET! And yet.

And yet. Here I am, typing this on an iPad (10.5”, this time). What happened, what changed? Basically, my expectations did. I realized I was trying to shoehorn the iPad into my ideal use-case vs. letting the strengths of the device inform how I would use it.

After returning the glorious piece of glass that is theiPad Pro 12.9”, I began to recognize the times where the freedom and focus provided by an iPad would be beneficial. Those half days where I co-work somewhere outside the home office. Those times when I need focus. The times when I’m on call and need a portable communications device. Does a laptop do 100% of what I need? Yes. But could an iPad do the most valuable 80% of what I need? My current working theory is that it can.

Here is how I think about my iPad Pro now:

Writing

A lot of what I do at work is communicating via writing. Long-form writing, Slack collaboration, blog posts, some emails, etc… The iPad is a great writing machine. I’ve installed Ulysses and now use the iPad as my primary long-form writing device.

Since I know Ulysses is one of those well-supported apps with excellent keyboard and landscape support (it really is, highly recommended), I can skirt the iPad app ecosystem issue I ran into during my initial experiment.

Focus

I am a big fan of creating space in your day to focus on what Cal Newport calls “Deep Work”. Focused time, free of distractions, for you to make progress on some strategic, big picture, work. Too much of our day is consumed by this alert and that notification and this ping from a coworker.

The iPad is my safe place.

I have all notifications turned off. The iPad is where big chunks of work happen and notifications are death to focus.

I almost went as far as not installing Slack, email and other work-related collaboration apps, but decided against it (for now, I am always re-evaluating)!

Portability

The reason I installed Slack and some other real-time collaboration tools is that those are necessary for when I’m on call. Having them on my iPad lets me use the iPad as my sole on-call device. I can grab this always-on, thin and lite device and not have to worry about the power source or any other accessories. It’s all bundled into this convenient package.

That little bit of convenience is incredibly valuable for high-frequency, high-inconvenience, use-cases like being on call.

The balance I made between these distracting apps and my desire for focus is to move them all off the main home screen. My main view is simply a dock with writing-centric apps and nothing else.

Ahhh… focus.

Future

Finally, this experiment is a little bit of a bet on my part on what the future of computing will be. I believe we are seeing the beginning of an evolution that will bring tablet devices (led by iPad) into the mainstream of computing.

I want to experience that progression first hand. Or at least enough of it to know why it doesn’t work for me and what that gaps remain.

If you see more posts from me, the experiment is working.

If not, well, get ready for round three 😱

Recursively List Files in Elixir

2016-09-05T00:00:00+00:00

Quick Elixir ditty to recursively list the files at a given path (relative or absolute):

defmodule FileExt do
  def ls_r(path \\ ".") do
    cond do
      File.regular?(path) -> [path]
      File.dir?(path) ->
        File.ls!(path)
        |> Enum.map(&Path.join(path, &1))
        |> Enum.map(&ls_r/1)
        |> Enum.concat
      true -> []
    end
  end
end

FileExt.ls_r("../exgen")
["../exgen/.git/COMMIT_EDITMSG", "../exgen/.git/config",
 "../exgen/.git/description", "../exgen/.git/HEAD",
 "../exgen/.git/hooks/applypatch-msg.sample",
 "..."]

 FileExt.ls_r("/Users/ryan/projects/exgen")
 ["/Users/ryan/projects/exgen/.git/COMMIT_EDITMSG",
  "/Users/ryan/projects/exgen/.git/config",
  "/Users/ryan/projects/exgen/.git/description",
  "/Users/ryan/projects/exgen/.git/HEAD",
  "/Users/ryan/projects/exgen/.git/hooks/applypatch-msg.sample",
  "..."]

Generate an Apple Pay CSR with OpenSSL

2014-11-06T18:07:56+00:00

When creating an Apple Pay certificate signing request, Apple specifies that you need to use a 256 bit elliptic curve key pair. To generate both the private key and the CSR using the openssl command line utility, do the following:

$ openssl ecparam -out private.key -name prime256v1 -genkey
$ openssl req -new -sha256 -key private.key -nodes -out request.csr -subj '/O=Your Name or Company/C=US'

The result will be a private key file at private.key and the CSR in request.csr. They should look something like this.

You will need the private key to decrypt the Apple Pay cryptogram so keep it in a secure place. The CSR you will then upload to Apple, which will sign the certificate for you to use in your iOS app.

Normally, your payment provider will generate the private key (which they will retain) and CSR for you, so doing this yourself won’t be necessary. However, if you’re a payment provider like Spreedly or are interested in managing more of the payment flow, this may be useful.

A few notes:

Use the prime256v1 elliptic curve when generating your private key as this is what’s used by Apple’s Keychain app when generating an EC key.
Apple will add/overwrite the UID, CN (common name) and OU (organizational unit) certificate fields with the associated merchant identifier so your CSR doesn’t need to specify them.

Exposing a Javascript API in a Web Page with Browserify

2014-10-09T18:07:56+00:00

When using Browserify to build and resolve your javascript library dependencies, it’s very easy to get a resulting bundle.js file that you can include in a browser with a simple script tag.

<script src="/assets/bundle.js"></script>

Including the bundle in this way will execute the code in your entrypoint (often main.js) which is where most online tutorials end and which might be all you need. However, how do you create a bundle that will expose an API to the including page? So you can do something like:

<script src="/assets/bundle.js"></script>
<script>
var lib = new MyLibrary();
</script>

You need to specify the standalone option to the browserify command (or API), which will export the API you expose in your entrypoint file in the given namespace. Here’s an example.

Given a library file where your main library functionality is defined:

var _ = require('underscore');

module.exports = MyLibrary;

function MyLibrary() {
  this.aSetting = true;
};

MyLibrary.prototype.doWork = function() {
  console.log(this.aSetting);
}

And your browserify entrypoint which exposes your library API:

module.exports = require('./lib')

At this point, if you were to build a bundle with browserify and include it in a web page, you wouldn’t be able to access MyLibrary. Since browserify makes sure everything is local scoped, and the web page doesn’t know how to deal with your top level export, it’s effectively hidden. The solution is to tell browserify to expose your exports with the standalone option.

As a command it looks like this:

$ browserify main.js --standalone MyLibrary > bundle.js

And if you’re using Gulp or similar the API options looks like:

browserify('./main.js', {
  standalone: 'MyLibrary'
})

With this resulting bundle you can now reference MyLibrary from the including html page.

<script src="/assets/bundle.js"></script>
<script>
var lib = new MyLibrary();
lib.doWork();
</script>

Time-Series Database Design with InfluxDB

2013-08-13T00:00:00+00:00

Here at Spreedly we’ve recently started using the time series database InfluxDB to store a variety of customer activity metrics. As with any special purpose database, using and designing for a time-series database is quite different than what you may be used to with structured (SQL) databases. I’d like to describe our experience designing our InfluxDB schema, the mistakes we made, and the conclusions we’ve come to based on those experiences.

The mark

Consider the following scenario, closely resembling Spreedly’s: You run a service that lets your customers transact against a variety of payment gateways. You charge for this service on two axes – by the number of gateways provisioned and the number of credit cards stored. For any point in time you want to know how many of both each of your customers has for their account.

Initially we setup two series (InfluxDB’s term for a collection of measurements, organizationally similar to a SQL database table) to store the total number of each item per account:

gateway.account.sample
payment-method.account.sample

On some regular interval we’d collect the number of gateways and payment methods (credit cards) for each account and store it in the respective series. Each measurement looked like:

{
  "time": 1400803300,
  "value": 2,
  "account_key": "abc123"
}

time is required by InfluxDB and is the epoch time of the measurement. The value is our value of the measurement at that time, and account_key is an additional property of that measurement.

Simple enough. This approach felt good and we went to production with this schema. That’s when we learned our first lesson…

Time-scoped queries

The first app that used the data in InfluxDB was our customer Dashboard product. It displays all your transactions and a simple view of your current billing counts (number of gateways and number of stored payment methods). Dashboard simply queried for the most recent measurement from each series for the current account:

select value
  from gateway.account.sample
  where account_key = 'abc123'
  limit 1

Since results in InfluxDB are ordered by default most recent first, the limit 1 clause ensures only the most recent measurement is returned for that customer (account).

All was fine initially, but as our dataset grew into the hundreds of thousands entries for each series we noticed our queries were taking quite some time to complete - about a constant 5s for every account. It turns out that these queries were incurring a full table scan, hence the constant (poor) performance.

Avoid a full table scan by always time-scoping your queries

In InfluxDB, the non-time fields aren’t indexed, meaning any queries that filter based on them require a full table scan (even if you’re only fetching a single result). The way to avoid a full table scan is to always time-scope your queries. Knowing this we modified our queries to only query against the previous 2 days worth of data (enough time to capture the most recent input):

select value
  from gateway.account.sample
  where time > now() - 2d
    and account_key = 'abc123'
  limit 1

Adding the where time > now() - 2d clause ensures that the query operates against a manageable set of data and avoids a full table scan. This dropped our query times from 5s (and growing) down to a steady 100ms - 200ms. (Keep in mind this is a remote instance of InfluxDB, meaning the bulk of that is in connection setup and network latency.)

InfluxDB response time reduction using time-scoped queries. Y-axis truncated for maximum obfuscation.

Obviously your use-case may differ wildly from ours. If your data is collected at unknown intervals, or in real-time, you don’t have the luxury of limiting your queries to a known window of time. In these situations it is wise to think about how to segment your data into series for optimal performance.

Series granularity

How many series should you have? How much data should you store in each series? When should you break out queries into their own series? These are all common questions when designing your time-series schema and, unfortunately, there is no concrete right or wrong answer. However, there are some good rules of thumb to keep in mind when structuring your data.

Continuing from our previous example: We were now using time-scoped queries to get the total number of gateways and cards for each account. While we were seeing good performance, each query was operating against a single series that contained data for all accounts. The query’s account_key condition was responsible for filtering the data by account:

select value
  from gateway.account.sample
  where time > now() - 2d
    and account_key = 'abc123'
  limit 1

As even this already time-scoped set of data grows, querying against a non-indexed field will start to become an issue. Queries whose conditions eliminate a large percentage of the data within the series should be extracted out into their own series. E.g., in our case we have a query that gets a single account’s count of stored gateways to the exclusion of all the other accounts. This is an example of a query that filters out the majority of the data in a series and should be extracted so each account has its own series.

Series are cheap. Use them liberally to isolate highly conditional data access.

If you’re coming from a SQL-based mindset, the thought of creating one series per account might seem egregious. However, it’s perfectly acceptable in time-series land. So that’s what we did - we starting writing data from each account into its own series (with each series’ name including the account key). Now, when querying for an account’s total number of stored gateways we do:

select value
  from account-abc1234.gateway.sample
  where time > now() - 2d
    ...

Since you have to know the key in question to access the right series, this type of design is most common with primary (or other well-known keys). But… not only can series be segmented by key, segmenting by time period is also possible. While not useful in our specific situation, you can imagine segmenting data into monthly series, e.g., 201407.gateway.sample or some other period, depending on your access pattern.

You can imagine…

Multi-purpose data

At this point your series are lean and efficient, well-suited for accessing a single type of query and data. However, sometimes life isn’t that clean and you have one set of data that needs to be accessed in many different ways.

For instance, at Spreedly, we’d like to have a business-level set of metrics available that shows the total number of gateways and payment-methods across all customers. We could just dump summary-level data into a new series (not a terrible idea), but we’re already collecting this data on a customer-level. It’d be nice not to have to do two writes per measurement.

Use continuous queries to re-purpose broad series by access pattern

Fortunately, InfluxDB has a feature called continuous queries that lets you modify and isolate data from one series into one or more other dependent series. Continuous queries are useful when you want to “rollup” time-series data by time period (e.g., get the 99th percentile service times across 5, 10 and 15 minute periods) and also to isolate a subset data for more efficient access. This latter application is perfect for our use-case.

To use continuous queries to support both summary and account-specific stats we need to create the parent series that contain measurements for each account.

{
  "time": 1400803300,
  "value": 2,
  "account_key": "abc123"
},
{
  "time": 1400803300,
  "value": 7,
  "account_key": "def456"
}

We can access this series directly to obtain the business-level stats we need across all customers:

select sum(value)
  from gateway.account.sample
  where time > now() - 1d

With continuous queries we can also use this parent series to spawn several “fanout” queries that isolate the data by account (replicating the account-specific series naming scheme from earlier):

select value
  from gateway.account.sample
  into account-[account_key].gateway.sample;

Notice the [account_key] interpolation syntax? This creates one series per account and stores the value field from each measurement into the new account-specific series (retaining the original measurement’s time):

{
  "time": 1400803300,
  "value": 2
}

{
  "time": 1400803300,
  "value": 7
}

With this structure we:

Only write the data one time into the parent series gateway.account.sample
Can perform summary level queries against this parent series
Have access to the highly efficient, constantly updated, account-specific, data series account-def456.gateway.sample etc…

This is a great use of fanout continuous queries. Also available are regular continuous queries which operate by precomputing expensive group by queries. I’ll skip over them for now since we’re not yet using them at Spreedly, but I encourage you to look at them for your use cases.

Naming and structure

Series naming and packet structure is a tough topic due to personal preferences, differences in client languages and highly varied access patterns. I’m not going to label the following as best-practices, instead I’ll present what we’ve found at Spreedly, our motivations, and let you decide whether it makes sense for you to apply.

Come up with a naming structure that conveys both the purpose of the series and the type of data contained within. At Spreedly it’s something like (and still evolving): [key].measured-item.[grouping].measurement-type. For instance, the series that contains the count of all gateways stored by account is gateway.account.sample. The account-specific version is: account-abc123.gateway.sample. The measurement-type component is highly influenced by the l2met logging conventions and deserves further discussion.
- count series record a specific number of times something happened in a specific period of time as an integer. Counts can be summed with other counts in the same series to perform time-based aggregations (rollups). Measured number of requests or transactions per minute are an example of a count series.
- sample series take a point in time measurement of some metric that supercedes all previous samples of the same series. Sum totals are a good example of this type of series, e.g., total revenue to date, or total number of payment methods. With each measurement in the series, previous measurements are no longer relevant, though they may still be used to track trends over time.
- measure series are similar to count series except that instead of being a simple representation of the number of times something happen, they can represent any unit of measure such as ms, Mb etc… Measurements are be mathmatically operable and can be summed, percentiled, averaged etc… CPU load and response times are examples of measure series.
Often there is a single value that represents the thing being measured, with the rest of the fields being meta-data or conditions. To facilitate re-usable client parsing we’ve found it nice to use the same field name across all series to represent the value of the measurement. Unsurprisingly, we chose value. All our series data contains a value field that contains the measurement value. This makes it easy to retrieve, which is especially useful in queries that select across multiple series or even merge results from multiple series into a single result set.

There’s a lot of subjectivity that goes into database design, independent of the storage paradigm. While SQL has been around for awhile and has well-known patterns, alternative databases, including time-series databases, are a bit more of a wild west. I’m hoping that by sharing our experiences we can prevent some common mistakes, freeing you up to create all new ones of your own!

Many thanks to Paul and Todd and the rest of InfluxDB for their tireless guidance on the subject

The New Gist: What It Is and What It Could Be

2012-12-13T00:00:00+00:00

Gist is an incredible tool by Github for quickly sharing code, text and files. It has syntax highlighting and rendering for a huge number of programming languages including Markdown for text. For many techies, including myself, Gist is an indispensable tool for quickly sharing code and content with coworkers.

Gist has been around for several years now and, when compared with the pace of development on the main Github.com property, has been relatively neglected. Thankfully, Github recently updated Gist with a fresh new codebase and UI. As a heavy user of Gist I have some thoughts on this update, where it hits the mark and where it’s still lacking.

Search

Search has long been sorely needed in Gist. It is not uncommon for power users to have several hundred to thousands of gists and the previous linear list-view based on creation date was inadequate. Immediate recall of a gist based on a search query was the primary use-case I had in mind when creating Gisted - a tool to quickly search and access all your gists. So, seeing a native Gist search feature was very welcome for me.

Unfortunately, it leaves a bit to be desired. Firstly the search is case sensitive. So searching for proposal is not the same as Proposal. When searching my gists I never care about the case and want to just quickly find the most relevant gist containing that term. Fortunately, I imagine this to be a very easy fix on Github’s end and expect it will be remedied shortly (based on nothing but my intuition).

Indexing

However, more fundamentally, search seems to only apply to the description of your gist (gists don’t have titles - the closest thing is what is labeled as the description). While I try to be very conscious of creating meaningful descriptions, when I search for them I often use some distinct term from within the gist content itself. Searching only based on description is like searching Google only based on the title of the web page.

Consider the results from the new gist search for a term I know exists: dev

Only one result? I think not. Now against descriptions and file contents:

There are lots of relevant results missed by Gist’s search mostly due to the lack of content indexing. Search can be a powerful utility for Gists but it needs some indexing refinement yet.

Advanced operators

Relevant but basic search is a must-have for most users. Search with filtering and other operators is a must-have for power users. For instance, filtering by owner is a great way to quickly list the gists you’ve starred by others. I like this implemented with the @ prefix notation and use it frequently:

The new Gist doesn’t seem to have filtering or any advanced features like phrases ("exactly this") or operators (AND, -). These tend to be built-in features of any search index so I imagine Github is easing into search and will turn these on once they feel comfortable with the infrastructure.

Lists

In the old Gist you really only had one way to view your gists. In a list of your created gists or your starred gists, ordered by when they were created. This was incredibly limiting. The new gist ushers in several refinements including:

The ability to sort gists by their updated date. However, this value is not sticky so I find myself always having to select it when I just want it as my default.
A much better partial rendering of each gist in the list, allowing you see more of the gist to know which one is the one you’re looking for.

These are just a few of the things that make using Gist a little more enjoyable than the old interface.

Revisions

Although gists have always been backed by a full git repo you didn’t see much of that benefit in the web UI. You had to clone the repo locally to see version diffs and manually fetch other remotes to compare and merge forked versions.

The new Gist takes a small step to solving this puzzle, allowing you to view diffs between your gist’s revisions.

However, it still doesn’t provide an easy way to view diffs or perform merges across forks. These are key collaboration features that would remove significant friction from using gists now. I can only hope Github is seriously thinking about enhancing this aspect of the product.

Content focus

The new Gist has a somewhat awkward focus on the gist files rather than the descriptions. I say awkward because, while I appreciate the direction of putting the content front and center, there are some artifacts that betray the intent.

For instance, when viewing a gist in a list it’s the filename of the gist that gets top billing:

However, gists can have multiple files making it an odd decision to choose only one (the first) to key off of.

Additionally, if files/content are the focus, they should be a first-class citizen in search but are instead ignored (as previously discussed).

Still missing

Some miscellaneous features I was hoping would be added in the new Gist include:

A resurrection of comment notifications! Gisted will do this for you, but it really should be a natively supported feature.
Markdown editing and rendering parity with Github proper. If you look at your standard project README on Github you’ll notice you can edit the Markdown inline with decent highlighting, preview your content and, when rendered, sections are automatically anchored. Markdown is such a core feature of text-based collaboration that parity here is essential.
A de-emphasis of the public gist-stream (now called “Discover Gists”). I just don’t see the value of randomly browsing new gists and think that real estate could be better used.

Summary

The new Gist is definitely an improvement over the old one. However I find it mostly just polishes existing features and doesn’t directly address some of larger issues.

I would encourage Github to focus of the main uses of Gist. From my perspective, gists are used mainly as a collaboration tool. While they’re backed by a full git repo, that is mostly an implementation detail. Commenting, managing collaborator modifications, and finding gists across several sources should be well supported use-cases.

I suspect we’ll see the pace of development on Gist quicken now that a new codebase is in place. Removing technical debt often removes roadblocks that may have prevented a product from evolving. I can only hope if I revisit this post several months from now I’ll have to significantly edit some of my more critical points.

Github has been incredibly supportive in my use of the Gist API and my work with them on this front only reinforces their developer-focused reputation. They’ll get Gist right, it’s just a matter of time.

Given my dependence on Gist for work I have a vested interest in its success. Any critical points made here were done so only in hopes of seeing it evolve into a better product.