Writing Styleguide
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…
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-54
foo:
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-2
root: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 blobsI use
vim
overnano
oremacs
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