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

	<!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>

	/* 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;
	});

	var getParseHeader = function () {
	return {
	"X-Parse-Application-Id": "ENTER_APP_ID",
	"X-Parse-REST-API-Key": "ENTER_API_KEY",
	"Content-Type": "application/json"
	};
	};

	var getParseUrl = function (className) {
	return "https://api.parse.com/1/classes/" + className;

	#!/bin/bash

	#post .js file contents to BaasBox to create plugin
	#usage bash postBaasBoxPlugin.sh sample.js

	#get fileName
	fileName="$1"

	#uncomment below line to read file contents to variable
	#codeContent=$(<$fileName)

	# 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

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

Claudio T. giastfader

A Very Short Guide to Writing Guides

Audience

Pronouns