Beginning to write Dev.to articles was intimidating for me, and a tutorial on writing articles would have helped reduce the barrier to entry. Now that I've written six articles, I've settled into a comfortable flow that I thought I'd share with anyone else interested in taking the plunge into writing their own technical articles.

I've tuned this process for my needs as a writer, ensuring I can consistently write technical articles with a specific structure, but I think it works well for opinion pieces as well.

The Setup

I keep all my articles in a GitHub repository so that I can access them from multiple computers and track changes as I go. Like coding, sometimes I'm unsatisfied with my changes, and I want to compare them to a previous version. A simple file version manager would also suffice.

File Structure

I keep my active articles in a drafts folder. When I publish an article, I prepend it with the date and move it to the published folder for ordering/archival purposes. This gives me a record of my articles and images in case I want to publish anywhere else or need to make a change.

├── README.md
├── drafts
│   ├── more_accessible
│   │   └── main.md
│   └── writing_process
│       └── main.md
├── package-lock.json
├── package.json
└── published
    ├── 2020_10_31_color_migration
    │   ├── hero.jpg
    │   └── main.md
    ├── 2020_11_07_testing_postcss
    │   ├── hero.jpg
    │   └── main.md
    ├── 2020_11_15_marginal_linting
    │   ├── hero.jpg
    │   ├── main.md
    │   └── reviewdog-annotation.png
    ├── 2020_11_16_use_datetime
    │   └── main.md
    ├── 2020_11_22_testing_time
    │   ├── hero.jpg
    │   └── main.md
    └── 2020_11_29_bad_variable_names
        ├── hero.png
        └── main.md

Package.json

I use Prettier with lint-staged to automatically format my articles after every commit. This is particularly helpful for any code blocks in .md files.

// package.json stub with the dependencies and scripts necessary for the commit hooks
{
  "scripts": {
    "lint": "prettier --ignore-path=.gitignore **/*.md",
    "lint:fix": "npm run lint -- --write"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,jsx,css,scss,md}": "prettier --write"
  },
  "devDependencies": {
    "husky": "^4.3.0",
    "lint-staged": "^10.5.1",
    "prettier": "^2.1.2"
  }
}

VSCode

I use Visual Studio Code to edit and preview markdown. I've tried Mark Text, and Typora, neither of which felt right for me - their rich text editing for markdown seems to struggle with undo/redo.

I use the following VSCode Plugins to help with my writing:

• Spell Right for basic spell checking.
• VSCode Prettier auto-formats my code on every save.
• Write Good encourages me to use active voice and cuts unnecessary words.

Here's my project level .vscode/settings.json for configuring the plugins:

{
  "editor.rulers": [100],
  "[markdown]": {
    "editor.wordWrap": "bounded",
    "editor.wordWrapColumn": 100
  },
  "editor.formatOnSave": true,
  "write-good.languages": ["markdown", "plaintext"],
  "languageToolLinter.serviceType": "public"
}

The Process

Ideas 💡

I initially struggled each week to come up with new article ideas, so I started tracking my thoughts as they popped into my head throughout the day. As I come up with ideas I add them as sections to README.md. To develop the idea, I add bullet points that I'd like to cover. Often these bullet points become the headings for my articles. If my computer isn't near, I add a short note on my phone to move to my README.md later.

Structure 🏗

When I get started on an article, I try to get the heading structure onto the page first. This helps me identify what I want to say and make sure I'm making an honest effort at having a flow to my article. At this point I run the structure by my editor (in my case, my wife, but whomever you have to get a second opinion can help).

First Draft 📝

Now that I have the idea and structure, it's time to write the article. In addition to the article itself, I build demos or test applications to verify technical accuracy. For instance, I made jest-postcss while writing Writing Cleaner Tests with Jest Extensions and an example repo for Adding New Lint Rules Without the Fuss. I embed interactive tools (repl.it, Code Sandbox) whenever possible through Dev.to's liquid tags to make the article more engaging.

Read Through 👀

I do a first pass to make sure everything makes sense to me. A lot of big edits and paragraph rearranging happen in this step. I try to leave the first draft sitting for a few hours or a day so I can come back to it with a fresh mind.

Listen to it 🎧

Because I struggle to see what is wrong with my writing just by reading it, I use Mac's text to speech to listen to my article. This helps catch phrasing that is hard to parse or sounds awkward when read aloud. This and the read through help limit the time my editor puts into the writing - she's doing it for free after all.

High-Level Feedback 🚥

At this point I ask my editor to look through the article for any big changes or gaps in the article. I try to not be too attached to anything I've written so far because anything is fair game for revisions.

Polish ✨

After addressing high-level comments, I ask my editor to walk through the entire article with me piece-by-piece to clean up wording. This is where we make sure the ideas are easy to understand for the reader. We no longer spend the whole time fixing passive voice now that I use the Write Good plugin.

Ship It! 🚢

For now I publish directly to Dev.to by copying my markdown files over, making sure to preview them for any issues. It's important to make sure liquid tags work before publishing since they don't render in VSCode's markdown preview.

Hero Images

Hero images help catch the reader's eye. They're an opportunity to show readers something about your article or yourself. I normally use a photo I've taken myself, but for articles with code I started using Carbon.now.sh to help give readers a clearer idea of the article's contents.

This was the hero image from my article, Stop Using "data" as a Variable Name

Conclusion

That's my whole process for writing technical articles. I hope it's helpful to anyone who wants to start writing and makes the process less intimidating. I'd love to hear what other tools, processes, or services people use for their writing.

You can also check out my template repo, which I'll try to keep up-to-date with any new practices I adopt.