Eric Redmond coderoshi

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 teenagers, so I shy away from images of pop icons and memes. I use jargon and words like "identify" rather than "peep this".

	# encoding: UTF-8
	require 'riak'
	require 'rsolr'
	require 'ap'

	client = Riak::Client.new(nodes: [{pb_port:10017}])

	people = client.bucket('people')
	map = Riak::Crdt::Map.new(people, 'eric', 'maps')
	map.registers['first'] = 'MY_NAME'

	## Set SC from off to on

	find /riak/dev -name riak.conf \| xargs sed -i -e "s/## strong_consistency = on/strong_consistency = on/"

	## restart each node in order

	for d in `ls /riak/dev`; do /riak/dev/$d/bin/riak restart; done

	# Register the FML plugin to middleman
	module Middleman::Renderers::FAQML
	def registered(app)
	begin
	require "faqml"
	app.before_configuration { template_extensions :fml => :html }
	::FAQML::Engine.set_default_options(
	:buffer => '@_out_buf',
	:generator => ::Temple::Generators::StringBuffer
	)

	source :rubygems
	gem 'sinatra'
	gem 'httparty'
	gem 'nokogiri'

	# Cashcatme. Just like pug bombing, but with flava
	#
	# cashcat me - Receive a cashcat
	# cashcat bomb N - get N cashcats

	module.exports = (robot) ->
	robot.respond /cashcat me/i, (msg) ->
	msg.http("http://cashcatme.heroku.com/bomb?count=1")
	.get() (err, res, body) ->
	msg.send JSON.parse(body).cats

	# Usage: (bracket followed by a comma-separated list of names)
	# hubot bracket Joe, Fred, Tony, Eddy

	https = require('https')

	# uses challonge to create a bracket with the given names
	module.exports = (robot) ->
	robot.respond /bracket\s+(.+?)$/i, (msg) ->
	names = msg.match[1]
	return unless names

	db.getAll('90s-emo', {
	where: { origin: "Madison, WI" }
	});

Eric Redmond coderoshi

A Very Short Guide to Writing Guides

Audience

Pronouns