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

	//from: https://groups.google.com/forum/?fromgroups=#!searchin/orient-database/OIdentifiable/orient-database/fwAmlTJy4-c/ne3wpgbSJOEJ

	public static ODocument getDoc(String name){
	OGraphDatabase db = OGraphDatabase ((ODatabaseRecordTx)ODatabaseRecordThreadLocal.INSTANCE.get());
	OIndex idx = db.getMetadata().getIndexManager().getIndex("doc.name"); //<<---- the index name
	ORecordId record = (ORecordId) idx.get( name );
	return (ODocument) record.getRecord();
	}

	int maxRetries=MVCC_MAX_RETRIES;
	boolean done=false;
	OConcurrentModificationException e =null;
	for (int i=1;i<=maxRetries;i++){
	try {
	Logger.debug("Creation of the edge. Attempt n. " + i);
	db.createEdge((ODocument)vertex1.reload().getRecord(),vertex2).save();
	done=true;
	Logger.debug("Edge created successfully after " + i + " attempts");
	break;

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

	#the BaasBox server address. NOTE: be sure to add the / at the end of the URL
	baasbox_address = "http://localhost:9000/"
	#the BaasBox instance application code
	baasbox_app_code = "1234567890"
	#the HTTP header to send
	headers = {u'X-BAASBOX-APPCODE':baasbox_app_code,u'Content-Type':'application/json'}
	#inserts a new user into BaasBox
	def insertuser (profile_object):
	#format the BaasBox user object
	res = requests.post(baasbox_address+"user" ,data=json.dumps(profile_object),headers=headers)

	import codecs #to manage unicode files
	import json #to manipulate JSON objects
	import datetime #to manipulate and format timestamps
	import requests #to call BaasBox APIs
	import base64 #to encode the Basic Auth header

	baasbox_address = "http://localhost:9000/" #the BaasBox server address. NOTE: be sure to add the / at the end of the URL
	baasbox_admin_user = "admin" #the BaasBox user to use when a BaasBox is called
	baasbox_admin_password = "admin" #the password to use
	baasbox_app_code = "1234567890" #the BaasBox instance application code

	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

	//Project definition
	{
	"name":"Project name",
	"url":"http://projectname.com",
	"issues":[{issue},{issue}] //see definition below
	}

	//Issue definition
	{
	"title":"A nasty bug",

	/* script: bb.check_user_exists */
	/* This script endpoint: /plugin/bb.check_user_exists */

	/*usage:
	GET /plugin/bb.check_user_exists?username=<username_to_check>
	/* returns error 404 if the specified username does not exists, otherwise it returns the public profile */

	http().get(function(req){
	var user=req.queryString.username[0];
	var res=Box.Users.find({

Claudio T. giastfader

A Very Short Guide to Writing Guides

Audience

Pronouns