The code and data behind xeiaso.net
blog: writing about writing
Signed-off-by: Xe <me@christine.website>
+202
+202
blog/doing-a-writing.markdown
+202
blog/doing-a-writing.markdown
···
1
+
---
2
+
title: Writing Coherently At Scale
3
+
date: 2022-06-26
4
+
tags:
5
+
- writing
6
+
---
7
+
8
+
As someone who does a lot of writing, I have been asked how to write about
9
+
things. I have been asked about it enough that I am documenting this here so you
10
+
can all understand my process. This is not a prescriptive system that you must
11
+
do in order to make Quality Content™️, this is what I do.
12
+
13
+
<xeblog-conv name="Cadey" mood="coffee">I honestly have no idea if this is a
14
+
"correct" way of doing things, but it seems to work well enough. Especially so
15
+
if you are reading this.</xeblog-conv>
16
+
17
+
<xeblog-hero file="great-wave-cyberpunk" prompt="the great wave off of kanagawa, cyberpunk, hanzi inscription"></xeblog-hero>
18
+
19
+
## The Planning Phase
20
+
21
+
To start out the process of writing about something, I usually like to start
22
+
with the end goal in mind. If I am writing about an event or technology thing,
23
+
I'll start out with a goal that looks something like this:
24
+
25
+
> Explain a split DNS setup and its advantages and weaknesses so that people can
26
+
> make more informed decisions about their technical setups.
27
+
28
+
It doesn't have to be very complicated or intricate. Most of the complexity
29
+
comes up naturally during the process of writing the intermediate steps. Think
30
+
about the end goal or what you want people to gain from reading the article.
31
+
32
+
I've also found it helps to think about the target audience and assumed skills
33
+
of the reader. I'll usually list out the kind of person that would benefit from
34
+
this the most and how it will help them. Here's an example:
35
+
36
+
> The reader is assumed to have some context about what DNS is and wants to help
37
+
> make their production environment more secure, but isn't totally clear on how
38
+
> it helps and what tradeoffs are made.
39
+
40
+
State what the reader is to you and how the post benefits them. Underthink it.
41
+
It's tempting to overthink this, but really don't. You can overthink the
42
+
explanations later.
43
+
44
+
### The Outline
45
+
46
+
Once I have an end goal and the target audience in mind, then I make an outline
47
+
of what I want the post to contain. This outline will have top level items for
48
+
generic parts of the article or major concepts/steps and then I will go in and
49
+
add more detail inside each top level item. Here is an example set of top level
50
+
items for that split DNS post:
51
+
52
+
```markdown
53
+
- Introduction
54
+
- Define split DNS
55
+
- How split DNS is different
56
+
- Where you can use split DNS
57
+
- Advantages of split DNS
58
+
- Tradeoffs of split DNS
59
+
- Conclusion
60
+
```
61
+
62
+
Each step should build on the last and help you reach towards the end goal.
63
+
64
+
After I write the top level outline, I start drilling down into more detail. As
65
+
I drill down into more detail about a thing, the bullet points get nested
66
+
deeper, but when topics change then I go down a line. Here's an example:
67
+
68
+
```markdown
69
+
- Introduction
70
+
- What is DNS?
71
+
- Domain Name Service
72
+
- Maps names to IP addresses
73
+
- Sometimes it does other things, but we're not worrying about that today
74
+
- Distributed system
75
+
- Intended to have the same data everywhere in the world
76
+
- It can take time for records to be usable from everywhere
77
+
```
78
+
79
+
Then I will go in and start filling in the bullet tree with links and references
80
+
to each major concept or other opinions that people have had about the topic.
81
+
For example:
82
+
83
+
```markdown
84
+
- Introduction
85
+
- What is DNS?
86
+
- Domain Name Service
87
+
- https://datatracker.ietf.org/doc/html/rfc1035
88
+
- Maps names to IP addresses
89
+
- Sometimes it does other things, but we're not worrying about that today
90
+
- Distributed system
91
+
- Intended to have the same data everywhere in the world
92
+
- It can take time for records to be usable from everywhere
93
+
- https://jvns.ca/blog/2021/12/06/dns-doesn-t-propagate/
94
+
```
95
+
96
+
These help me write about the topic and give me links to add to the post so that
97
+
people can understand more if they want to. You should spend most of your time
98
+
writing the outline. The rest is really just restating the outline in sentences.
99
+
100
+
## Writing The Post
101
+
102
+
After each top level item is fleshed out enough, I usually pick somewhere to
103
+
start and add some space after a top level item. Then I just start writing. Each
104
+
top level item usually maps to a few paragraphs / a section of the post. I
105
+
usually like to have each section have its own little goal / context to it so
106
+
that readers start out from not understanding something and end up understanding
107
+
it better. Here's an example:
108
+
109
+
> If you have used a computer in the last few decades or so, you have probably
110
+
> used the Domain Name Service (DNS). DNS maps human-readable names (like
111
+
> `google.com`) to machine-readable IP addresses (like `182.48.247.12`). Because
112
+
> of this, DNS is one of the bedrock protocols of the modern internet and it
113
+
> usually is the cause of most failures in big companies.
114
+
>
115
+
> DNS is a globally distributed system without any authentication or way to
116
+
> ensure that only authorized parties can query IP addresses for specific domain
117
+
> names. As a consequence of this, this means that anyone can get the IP address
118
+
> of a given server if they have the DNS name for it. This also means that
119
+
> updating a DNS record can take a nontrivial amount of time to be visible from
120
+
> everywhere in the world.
121
+
>
122
+
> Instead of using public DNS records for internal services, you can set up a
123
+
> split DNS configuration so that you run an internal DNS server that has your
124
+
> internal service IP addresses obscured away from the public internet. This
125
+
> means that attackers can't get their hands on the IP addresses of your
126
+
> services so that they are harder to attack. In this article, I'm going to
127
+
> spell out how this works, the advantages of this setup, the tradeoffs made in
128
+
> the process and how you can implement something like this for yourself.
129
+
130
+
In the process of writing, I will find gaps in the outline and just fix it by
131
+
writing more words than the outline suggested. This is okay, and somewhat
132
+
normal. Go with the flow.
133
+
134
+
I expand each major thing into its component paragraphs and will break things up
135
+
into sections with markdown headers if there is a huge change in topics. Adding
136
+
section breaks can also help people stay engaged with the post. Giant walls of
137
+
text are hard to read and can make people lose focus easily.
138
+
139
+
Another trick I use to avoid my posts being giant walls of text is what I call
140
+
"conversation snippets". These look like this:
141
+
142
+
<xeblog-conv name="Mara" mood="hacker">These are words and I am saying
143
+
them!</xeblog-conv>
144
+
145
+
I use them for both creating [Socratic
146
+
dialogue](https://en.wikipedia.org/wiki/Socratic_dialogue) and to add prose
147
+
flair to my writing. I am more of a prose writer [by
148
+
nature](https://xeiaso.net/blog/the-oasis), and I find that this mix allows me
149
+
to keep both technical and artistic writing up to snuff.
150
+
151
+
<xeblog-conv name="Cadey" mood="enby">Amusingly, I get asked if the characters
152
+
in my blog are separate people all giving their input into things. They are
153
+
characters, nothing more. If you ever got an impression otherwise, then I have
154
+
done my job as a writer _incredibly well_.</xeblog-conv>
155
+
156
+
Just flesh things out and progressively delete parts of the outline as you go.
157
+
It gets easier.
158
+
159
+
### Writing The Conclusion
160
+
161
+
I have to admit, I really suck at writing conclusions. They are annoying for me
162
+
to write because I usually don't know what to put there. Sometimes I won't even
163
+
write a conclusion at all and just end the article there. This doesn't always
164
+
work though.
165
+
166
+
A lot of the time when I am describing how to do things I will end the article
167
+
with a "call to action". This is a few sentences that encourages the reader to
168
+
try the thing that I've been writing about out for themselves. If I was turning
169
+
that split DNS article from earlier into a full article, the conclusion
170
+
could look something like this:
171
+
172
+
> ---
173
+
>
174
+
> If you want an easy way to try out a split DNS configuration, install
175
+
> [Tailscale](https://tailscale.com/) on a couple virtual machines and enable
176
+
> [MagicDNS](https://tailscale.com/kb/1081/magicdns/). This will set up a split
177
+
> DNS configuration with a domain that won't resolve globally, such as
178
+
> `hostname.example.com.beta.tailscale.net`, or just `hostname` for short.
179
+
>
180
+
> I use this in my own infrastructure constantly. It has gotten to the point
181
+
> where I regularly forget that Tailscale is involved at all, and become
182
+
> surprised when I can't just access machines by name.
183
+
>
184
+
> A split DNS setup isn't a security feature (if anything, it's more of an
185
+
> obscurity feature), but you can use it to help administrate your systems by
186
+
> making your life easier. You can update records on your own schedule and you
187
+
> don't have to worry about outside attackers getting the IP addresses of your
188
+
> services.
189
+
190
+
I don't like giving the conclusion a heading, so I'll usually use a [horizontal
191
+
rule (`---` or `<hr
192
+
/>`)](https://www.coffeecup.com/help/articles/what-is-a-horizontal-rule/) to
193
+
break it off.
194
+
195
+
---
196
+
197
+
This is how I write about things. Do you have a topic in mind that you have
198
+
wanted to write about for a while? Try this system out! If you get something
199
+
that you like and want feedback on how to make it shine, email me at
200
+
`iwroteanarticle at xeserv dot us` with either a link to it or the draft
201
+
somehow. I'll be sure to read it and reply back with both what I liked and some
202
+
advice on how to make it even better.