Claudio T. giastfader

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

	I was drawn to programming, science, technology and science fiction
	ever since I was a little kid. I can't say it's because I wanted to
	make the world a better place. Not really. I was simply drawn to it
	because I was drawn to it. Writing programs was fun. Figuring out how
	nature works was fascinating. Science fiction felt like a grand
	adventure.

	Then I started a software company and poured every ounce of energy
	into it. It failed. That hurt, but that part is ok. I made a lot of
	mistakes and learned from them. This experience made me much, much


	function scrapeGoogle() {

	var searchResults=UrlFetchApp.fetch("https://www.google.co.uk/search?q="+encodeURIComponent("keyword finder tool")+"&num=30",{muteHttpExceptions:true});

	var titleExp=/<h3 class=\"r\">([\s\S]*?)<\/h3>/gi;
	var urlExpression=/<h3 class=\"r\">([\s\S]*?)\&amp\;/gi;


	var titleResults=searchResults.getContentText().match(titleExp);

	/* script: venues.fs.search */
	/* This script endpoint: /plugin/venues.fs.search */

	on('install',function(installEvent){
	var success = Box.DB.createCollection('venues-cache-queries');
	var success = Box.DB.createCollection('venues-cache-answers');

	return true;
	});

	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<meta http-equiv="Content-Language" content="en" />
	<meta name="Author" content="Pawel Pabian, Pawel Nejczew http://implix.com" />
	<title>Demonstrates how to add new contact to campaign.</title>

	<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>

	"""
	Exports Issues from a specified repository to a CSV file

	Uses basic authentication (Github username + password) to retrieve Issues
	from a repository that username has access to. Supports Github API v3.
	"""
	import csv
	import requests

	OGraphDatabase db = OGraphDatabase ((ODatabaseRecordTx)ODatabaseRecordThreadLocal.INSTANCE.get());
	Collection<OClass> classes;
	classes = db.getMetadata().getSchema().getClasses();

	# Build Passes
	curl -d "room_id=ourRoom&from=BuildBot&message=Build+Status:+Passing&color=green" https://api.hipchat.com/v1/rooms/message?auth_token=AUTH_TOKEN_HERE&format=json

	# Build Fails
	curl -d "room_id=ourRoom&from=BuildBot&message=Build+Status:+Failing&color=red&notify=1" https://api.hipchat.com/v1/rooms/message?auth_token=AUTH_TOKEN_HERE&format=json

	#!/bin/bash
	# chkconfig: 345 20 80
	# description: Play start/shutdown script
	# processname: play
	#
	# Instalation:
	# copy file to /etc/init.d
	# chmod +x /etc/init.d/play
	# chkconfig --add /etc/init.d/play
	# chkconfig play on

Claudio T. giastfader

A Very Short Guide to Writing Guides

Audience

Pronouns