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

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

The footer should inculude the following sections:

  • Thanks
  • Related Material

Technical Pieces

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

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

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.

References

See https://www.andrewhowden.com/