Michael van der Nest michaelvdnest

I'm t9md

My editor history: Vim > Emacs > Vim > Atom

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".

Pronouns

Locate the section for your github remote in the .git/config file. It looks like this:

[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = git@github.com:joyent/node.git

Now add the line fetch = +refs/pull/*/head:refs/remotes/origin/pr/* to this section. Obviously, change the github url to match your project's URL. It ends up looking like this:

	@echo off

	cd %~dp0

	set MSYSTEM=%~1
	set _TERM=%~2
	set _SH=%~3
	set _ARGS=%~4

	REM If MSYSTEM is empty, uses MSYS.

	<#
	Token-replacement template engine for PowerShell courtesy to http://www.bricelam.net/2012/09/simple-template-engine-for-powershell.html
	Usage:
	Merge-Tokens 'Hello, $target$! My name is $self$.' @{ target = 'World'; self = 'Brice' }
	#>

	function Merge-Tokens($template, $tokens)
	{
	return [regex]::Replace($template, '\$(?<token>\w+)\$',
	{ param($match) $tokens[$match.Groups['token'].Value] })

	target hw1
	sources
	hw1.mlb
	hw1.main.sml
	end

	option compiler = mlton
	option output = hw1
	end