mkb mkb

‎"Rationality is what we do to organize the world, to make it possible to predict. Art is the rehearsal for the inapplicability and failure of that process." - Brian Eno

"Making something great seems like it should be the end of the process, but it isn’t. You can make something great, and nobody knows. That’s not what we’re taught to believe."

-- Jerry Holkins, aka Tycho of Penny Arcade

http://feeds.penny-arcade.com/~r/pa-mainsite/~3/-bYkmZtYkIU/benevolence

A Very Short Guide to Writing Guides

This is just a few thoughts on the topic of writing technical guides. This was intended for Basho's engineering team, but this may apply to open source projects in general.

Audience

It's commonly preached that the first step in writing is to identify your audience; to whom are you writing? This is the most well known, most repeated, and most overlooked step of writing in general and technical writing in particular. Take this document, for example. My audience is technical people who need to communicate technical information, and not teen girls, so I shy away from images of pop icons riding unicorns. I use jargon and words like "identify" rather than "smokin' out".

Pronouns

@mojinations So what would you use something like gist.io for?

Their own writeup identifies the main use case: I want to write something which is too long for a tweet but which doesn't belong on my blog. The situation doesn't arise often enough for me to bother setting up a Tumblr.

Of course one could simply use gists for this purpose. The advantage of gist.io is that the result is more presentable for consumption by a nongeek audience.

This presupposes that we are capable of writing for a nongeek audience.

I've been rejiggering my prompt. The story so far...

have

left side

id@host - arguably useless yet i find them reassuring
git branch name - in red if master
git branch dirty
cwd

	{
	"color_scheme": "Packages/User/Baby, The Code Shines Bright.tmTheme",
	"trim_trailing_white_space_on_save": true,
	"trim_automatic_white_space": true,
	"ensure_newline_at_eof_on_save": true,
	"tab_size": 2,
	"translate_tabs_to_spaces": true,
	"highlight_modified_tabs": true,
	"save_on_focus_lost": true,
	"font_face": "Inconsolata",


	# This line in my test...
	EY::Statsd.should_receive(:push)

	# ...causes this line in my app to fail...
	EY::Statsd.push(:keymaster).increment

	# The fix is...
	EY::Statsd.should_receive(:push).and_return(stub(:increment => nil))

	#!/usr/bin/env ruby

	# Props to @watersb, @ussintega, and @climagic

	one = "Mitt Romney and Paul Ryan"
	two = "My ultimate Ayn Rand porn"

	def sorted_letters(sentence)
	sentence.downcase.gsub(/\s+/, '').chars.sort.join
	end

	{
	"color_scheme": "Packages/User/Baby, The Code Shines Bright.tmTheme",
	"trim_trailing_white_space_on_save": true,
	"trim_automatic_white_space": true,
	"ensure_newline_at_eof_on_save": true,
	"tab_size": 2,
	"translate_tabs_to_spaces": true,
	"highlight_modified_tabs": true,
	"save_on_focus_lost": true,
	"font_face": "Inconsolata",

	[branch]
	autosetupmerge = true
	[user]
	name = Michael Brodhead
	email = [email protected]
	[color]
	ui = true
	[push]
	default = current