Cheatography.com — The Missing Manual

Cheatography.com is a free website for creating and sharing generic cheat sheets.  I wanted to create a cheat sheet of JavaScript value/type/object basics to release in tandem with my next post on JavaScript essentials, so I just tried using the site for the first time and found it a surprisingly painful experience.

Don't get me wrong — it's a great idea, and I'm glad Dave Child created it. Maybe I'm just spoiled by how awesome my first experience using a popular geek pet project usually is.

When I first arrived at the site and started poking around, I was confused by the concepts, the user interface, the workflow, and especially the layout options. To top it all off, the help section contained exactly one document on the one topic I actually wasn't interested in. :)

But I don't want spent a whole post bitching about free stuff and indulging in a sense of entitlement. Let's help! I present to you: Cheatography.com — The Missing Manual.

Architecture

The site allows logged-in users to create cheat sheets, which are composed of content blocks.

The idea behind content blocks is that they can be reusable. For example, if you were making two cheat sheets about HTTP and REST APIs, and you wanted to include a list of HTTP status codes in both, you could create one content block for it and then include it in both cheat sheets.

Both the individual content blocks and the cheat sheet as a whole can have the following metadata:

• Name (for content blocks, this appears in the header of the block)
• Status (Draft/Published)
• Description (for searching; not included on sheet)

Cheat Sheet

The cheat sheet can have the following additional metadata:

• Tags (for searching/browsing)
• Type (hosted on Cheatography or external link)
• Color (will be used by the content block header and separators)
• Content Blocks

You can only pick your own blocks to add to the sheet (it's likely sharing is on the wishlist). Every sheet has three fixed-width columns. You can drop as many blocks into each as you like, and drag/drop to reorder them. The sheet can expand to any length; it isn't limited to the height of a physical page (11").

Content Block

The actual layout of the content block's content depends on the layout you choose. (Layout details covered below.) The form adjusts to the structure of the layout, and entering content in the bottom row's cells (when using a list layout) will automatically add a new empty row to the bottom of the form.

In addition to the main content area, all blocks can have an optional note which is added to the bottom.

Style

The color of the header and separators will be determined by the cheat sheets the block is added to. Other than the layout, the only content styling options you have are simple text markup for italics, bold, and ^superscript, which can be used on any content and content note text.

The content note and the Text layout's input, which are both textarea inputs, allow newlines which will be converted into line breaks. URLs will be autolinked.

Layout

There's a Live Preview section in the right sidebar when editing a content block that is supposed to show you what the block will look like as you edit it. Unfortunately, in my browser (Firefox 15) it showed the header and note, but not the actual content area, making it impossible to know what the layouts actually look like without going through one-by-one, choosing them, adding some content, and saving it to see the result.

So that's what I did. Here are descriptions and screen shots for eight of the layout options. I skipped Video (similar to Image) and Live Content, which is the one thing with a help section.

Plain → Text

The content area for this layout is simply one big textarea. As I mentioned above, newlines are allowed and respected.

Lists → One to Four Columns

These layouts give you a tabular structure, with unlimited rows of one to four columns (the layouts are named by the number of columns they provide).  The column widths are not fixed, they adjust to the quantity of text in each column.

If you leave a cell empty, it will show up as empty.  However, if you leave all but one cell empty, the one cell with content will expand to fill the width of the row, which is convenient for adding subheaders or mid-block notes.

Lists → Bar Chart

I haven't yet seen a cheat sheet that uses this layout.  It gives you a set of rows, each row having a label and a numeric value which is converted into a proportional horizontal bar.

Lists → Question and Answer

This layout has a "dictionary" (key/value) structure, with the value displayed indented below the key.

Media → Image/Video

These layouts let you embed an image or video.  The image will be scaled down to a width of 270px (client-side).  Clicking on it pops up the full-size version.

Plain → Text with Note

Here's what the content note looks like when you use it.

Epilogue

To get some ideas on how to use the layouts and styles to express information, browse a few of the more popular sheets on the site:

• AngularJS 
• Regular Expressions 
• Linux Command Line

After you publish your sheet, you can share it or download it as a PDF.  There is not yet any kind of embedding option.

All in all, Cheatography.com is an important service and represents a real innovation in the software tool ecosystem.  While it has many rough edges, it's also less than a year old.  I look forward to watching it continue to evolve.

Honorable Mention

Don't want to go before I mention the alternative: Cheat, the gem and website. This wonderful gem gives you a command-line utility called `cheat` which lets you view, add, and edit textual cheat sheets from the online database.  They're designed to be viewable in your console, but you can browse/edit them on the website as well.

PS-When I've got a few sheets worth sharing, I'll add a new page to the navbar to host them.  If you create any Ember.js-related sheets, post a comment about it so I can include them in the list.