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

Pronouns

coderoshi

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

coderoshi

Verifying my Blockstack ID is secured with the address 1r2LNQFgRi9V8jT7aNFdyis4bZDBnmZ7k https://explorer.blockstack.org/address/1r2LNQFgRi9V8jT7aNFdyis4bZDBnmZ7k

coderoshi

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

coderoshi

client['roflcopter']['key0']

coderoshi

# 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
      )

coderoshi

# 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

coderoshi

# 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

coderoshi

exports.cors = (req, res)->
  origin = (req.headers.origin || "*")
  if req.method.toUpperCase() == 'OPTIONS'
    res.writeHead 200,
      'Access-Control-Allow-Origin': origin
      'Access-Control-Allow-Credentials': true
      'Access-Control-Allow-Methods': '*'
      'Access-Control-Allow-Headers': 'Accept, Authorization, Cache-Control, Content-Type, Origin, Referer, User-Agent, X-CSRF-Token'
      'Content-Type': 'text/plain'
      'Server': 'jsonapi'

coderoshi

neo4j = require('./caching_client').createClient
  port: process.env.NEO4J_PORT
  host: process.env.NEO4J_HOST
  username : process.env.NEO4J_LOGIN
  password : process.env.NEO4J_PASSWORD

neo4j.runCypher 'START x = node(0) RETURN x', (err, output, res)->
  if err
    console.log err.message
  else