Skip to main content

A Guide to Writing

Most of the content on this page is derived from my learnings at the O'Reilly event, Fundamentals of Technical Writing. The information that follows is an adaptation and summary of this event.

Preparation​

Type of writing​

Before we start writing, we need to figure out the type of our writing. There are four types of writing:

  • Reference: The goal is to transfer information, like the documentation of a library or a framework.
  • Tutorials: The goal is to transfer skills, like the tutorials on the official website of a library or a framework.
  • Pitch: The goal is to cause action, like a marketing email or a job application.
  • Story: The goal is to transfer experience.

Writings usually have a combination of these types. For example, a tutorial can have a reference section, or a pitch can have a story section.

Audience​

It's also important to know for whom we are writing. For example, in these documents, I'm mostly writing for myself and people who are like-minded. It's important to clarify the audience so that the writing would not be a waste of time for both the writer and the reader.

Step 1: Creating the components of the writing​

To get started we need to have some components, which are the things we want to write about. These components can come from various places. At this stage we don't care about the order of the content, we just want to get the ideas out of our head.

This part is adapted from Aristotle's Art of Rhetoric book. There are three places where we can get ideas from for writing:

  • Head
  • Heart
  • Behaviors

Answering 6ws (actually 5ws and 2hs) about the topic gives us some ideas about the writing:

  • What: the nature of the topic.
  • Who: the target audience of the topic.
  • When and Where: the time and place of the topic.
  • Why: the problem that the topic is trying to solve.
  • How: the solution for the topic.
  • How much: the numbers about the topic.

Heart​

Ideas can come from the emotions that are involved in the topic. There are 8 basic emotions and they mix into each other to create more complex emotions.

Behaviors​

Behaviors associated with the topic can also be a source of ideas. These behaviors usually come from:

  • Personalities and characters
  • Ethics and values
  • Habits and routines
  • Experiences
  • Expectations

Capturing ideas​

As we don't care about the order of the content at this stage, mindmap is a useful tool for capturing ideas. The topic can be broken down into subtopics, then each subtopic would get their own Head, Heart and Behaviors sections.

Example​

TBD

Step 2: Motivating the audience​

Pinpoint the problem​

Unless we're writing a reference document, the writing needs to have some characteristics so that the audience would be motivated to read through it. One way to do this is to wrap it with a problem and make the writing a solution or a cause of the problem.

So, the next step is to associate each component we've created in the previous section with a problem. The Behavior components are usually the most fruitful ones for this step. It's good to note that finding problems is one of the most important parts of the writing process and the better and more believable the problem is, the better the writing will be.

Example​

TBD

Step 3: Creating the outline​

The OODA loop​

The OODA loop is a decision making process that was created by John Boyd, a military strategist. It stands for:

  • Observe: you are passively observing the environment.
  • Orient: something in the environment triggers you, and you start to actively observe the environment to assess possible actions.
  • Decide: you decide on an action.
  • Act: you act on the decision.

The OODA loop is a good model for creating the outline of the writing as it creates a natural flow for the reader to follow. In writing, the OODA loops are usually called arcs.

Using the OODA loop​

Now that we have the components and the problems, and we know what the OODA loop is, we can start creating the outline by using the OODA loop. It might be easier to start writing the outline from the act part of the loop and traverse the loop backwards. Act and decide are usually about the solution we're providing. Orient comes from the problem we've defined for the component and observe comes from facts about the context and the environment of the component.

At this stage, it's important to not get into the details of the writing. The goal is to create a high-level outline of the writing so each part should not be more than one or two sentences.

Example​

TBD

Step 4: Refinement​

At this stage, we have much more content than we need. We need to refine the content to make it more concise and to the point. We go through these steps to do this:

Audience's attention span​

The arc's length should not exceed the reader's attention span. On average it's around 10 minutes or five pages. So, we need to make sure that the arc doesn't take longer than that, otherwise the audience would lose interest. It doesn't mean that the arc should take exactly 10 minutes, it can be as short as a paragraph as well. It's also a good idea to keep the length of all arcs consistent.

Triage​

Not every component should be included in the writing. So, we need to triage the components into 3 categories:

  • OK
  • Demote
  • Cut

The Demote components would be appendices or footnotes on the book or document, or the slides in the presentation that will be kept at the end of the presentation as prepared material for the questions that might arise. The Cut components would be removed from the writing.

Example​

TBD

Step 5: Writing up​

It's time to write up the content of each component. We've selected the components that we want to write, we have the OODA loops, and each component doesn't exceed the audience's attention span. So, we can start writing up the content of each component.

The "tent pole" method​

We can use the "tent pole" method to write up the content of each component. The "tent pole" method is a method that is used in writing screenplays. It's a method for writing the key points of each scene in the screenplay. We can use this method to write the key points of each component.

So, we can do the following for each component:

  1. Write the key points of each stage of the OODA loop.
  2. Write a paragraph for each key point.

Structure​

Now we have lots of unstructured paragraphs. Next step would be to structure the writing so that it'll make it possible for the audience to explore through it since almost none would follow the writing in a linear way and they would skim through it to see if it's worth their time and look for the parts that are interesting to them.

We can use the following tools to structure the writing:

  • Headings
  • Lists
  • Tables
  • Icons
  • Diagrams
  • Code blocks
  • Side panels

If a paragraph can be replaced with or shorten by one of these tools, it's a good idea to do so because these structures are the first things that get the audience's attention and they convey the message much faster than a wall of text.

Example​

A good example of structured writing can be found in tabloid newspapers and magazines. They've been evolved to attract the audience's attention for a long time and they're good at it.

Other notes​

Fighting the writer's block​

These might be reasons why writing feels difficult or impossible:

Lack of interest​

If there's a lack of interest in writing, maybe it's because the problem is not defined clearly, similar to the way we encourage the audience to read the writing. It's ok not to write anything and spend more time on finding the problem. So, we can just spend more time on finding the problem.

Fear of failure​

Fear of failure is a common blocker to writing. We can start by intentionally writing a poor version to overcome this block.

It'll have two benefits:

  1. The writing would not be as bad as it was imagined.
  2. We have something to iterate on, we can edit, rewrite, and improve it.

Hard to start​

When it's hard to start, it's a good idea to start anywhere it's easier to start with. We can start with the ending, middle, or even the middle of a sentence. It's also a good idea to start with the easiest part.

Tools​

There are some tools that might help with the writing process:

  • Paper and pen
  • Mindmaps
  • Legal yellow pads
  • Editors or formats with outline support (like markdown or org-mode)
  • Disconnecting from the internet or blocking the social media
  • SEO tools that help us find the right words to use (e.g., https://seoscout.com/tools/text-analyzer)
  • Pomodoro technique