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.
Top comments (12)
This looks kinda like the workflow I've used.
Saving all the posts to a private GitHub repo so I can access them in any pc.
Using VSCode with the
markdown-all-in-oneand Vim extensions and boom much more efficient writing than when I used the dev.to simple markdown editor and had to got go back and forth between the edit and preview tabs 😅Great post, it's a nice intro for those who haven't found their workflow yet
Thanks for sharing, that’s exactly what it’s intended for 🙂
I’m also selfishly looking to hear what others are doing so I can refine my setup further.
Thanks for getting straight to valuable content, without shameless self-plugs and unnecessary preamble... I too hope to avoid this, as it's been a pain point in my years on the consuming end of like content.
I am now also getting into dev content creation; I'm not sure if you've exactly worked out your target audience, but I'm it (or partially representative of it). Currently, my main struggle is knowing how much information is enough, and what I can assume that my will-be audience already knows. Sure, time will tell; but sometimes you need to sharpen an axe before it can chop down a tree.
For example, a current dilemma is for a tutorial article and video: I'm really stoked about where web components are finally going, so I chose it as my first topic. To work with web components irl, there remains this inherent tooling step, and so the dilemma is this: should I walk through setup stepwise (i.e. webpack and babel installation and configuration) or provide a starter repo, introduce the subject and why I believe it's so important, and get straight to it?
I understand this is not your problem, and I may very well represent competition on some level (trust, you're miles ahead of me, my friend)... I only wrote this so that you might consider elaborating on your process of content selection and your scoping for your articles as well.
I'm, so far, very impressed with Write Good, and plan to add the "Listen to it" step to my workflow. Thanks again for pouring your hard-earned time into creating content for people like me.
Thanks, I’m glad it was helpful! Honestly, I’m doing this to improve my writing, and to try to be less afraid of learning and even failing in public.
For me, my audience is either me X days/weeks/months/years ago, or someone that I’ve interacted with recently that I didn’t have the words to help them as effectively as I would have liked.
I don’t think I’m any authority on what will be popular, but one thing I’ve noticed is that the more accessible the content is to a beginner audience the better it does. It’s not gonna stop me from writing about developer ergonomics when writing an ESLint plugin, but I need to be ok with that article not getting much of an audience.
This is really similar to my workflow as well. It's really important to have a solid structure/outline before you start writing.
Also, I use StackEdit with a GitHub workspace for writing. I'll have to try VSCode though!
That’s a cool idea, maybe that can skip my iPhone notes step at least.
I (perhaps wrongly) assumed that the native editors would be better, but kept finding myself getting tripped up by its assumptions of wanting to undo entire paragraphs instead of a bad formatting.
Very helpful
Nice article, very helpful, thank you!
Thanks for this post, I am very new to writing technical posts and I did struggle with my workflow! I guess there's no reason why we shouldn't employ the same approaches to writing articles as code 👍
Are you using this repo for all your articles? (I am looking for the current here My Dev.to Writing Process)
The articles repo is private, that’s a template with examples for anyone that wants to use it as a starter.
Cool setup I have just been using Typora and storing all of my files on my local machine. Might try adding a version control setup instead.