Writing Styleguide

2 min readApr 5, 2018

This is a personal styleguide for medium, such that I can keep consistent while writing things. It’ll evolve, and not all writings will be consistent — it’s aspirational.

Article Structure

Header

The header should include a header image, for visibility when published in publications. The image should be 800x300

Footer

The footer should inculude the following sections:

Thanks
Related Material

Technical Pieces

Assumptions

Document in a limited way the knowledge required to understand the post, and the audience that it is intended for.

Series

Document at the beginning of each series all previous posts in the series
At the conclusion of the series, create a review piece that summarises the series and experiences, and links all of the relevant pages.

Tutorials / Debugging

Paste the exact error into the article, somewhere. Google likes it.

File Snippets

With each file snippet, add to a comment at the top of the file the (perhaps hypothetical) path to the file on disk, as well the line reference of the file in the following form:

# etc/fleet/config.yml:48-54foo:
  bar: "baz"

For content that’s expressed as stdout, we can use the psuedo file /dev/stdout. For example, given the command:

$ cat /etc/passwd

We can use the syntax

# /dev/stdout:1-2root:x:0:0:root:/root:/bin/bash

Process Output

Where a process has been output we can use the syntax as follows:

$ kubectl describe pod kolide-fleet-fleet-56b5c7f7c9-gkwpl #15-16,31-33...
Containers:
  fleet:
    ...
    Requests:
      cpu:      100m
      memory:   256Mi
    ...

Notably:

The output has been truncated, which we express with ...
The command has been suffix # ${START}-${END},${START}-${END} leaving it syntactically valid, but descriptive

Code

Bash

Prefix bash commands with the $ character

$ cat /dev/null

Software

Where software is written in line, use the inline code syntax. For example:

I use jq to navigate JSON blobs
I use vim over nano or emacs as the one true editor

Distribution

Scheduled

Distribution should be over the following channels;

Buffer (Twitter, Facebook)
LinkedIn (Full Article)
Telling your mum

And on either a Tuesday or Saturday at 2pm GMT. If there are no further posts scheduled, it’s fine to take the post that was posted on the opposite day, a week ago. For example, if there is no post on Saturday the 14th, take the post from Tuesday the 4th.

Indexed

Linked-in as a publication