My technical writing workflow

Thanks to writing docs for my side project Production Ready Forms I improved my writing workflow.

Previously, I was jumping between multiple editors. I had copies of the same text on git, cloud drive, Grammarly… It was a mess!

Now I use only two editors with extensions. VSCode & Hemingway Editor plus extensions like Spell Right, Grammarly.

Thanks to that I can keep a single source of truth for my articles on a git repository. I also avoid too much context switching.

1. Write the raw text in markdown using VS Code

I write raw markdown text inside VSCode. Previously I used Typora which is a great editor but I missed my shortcuts and custom settings from VSCode.

Also, I wanted to simplify the process so reducing the number of editors seems like a good idea. I needed to use VS Code anyway to work with the blog’s code & push changes to the git repository.

Protection from spelling errors

I use Spell Right extension so all my typos are quickly pointed out.

Set up the extension to use proper language in markdown files. I decided to use English – United Kingdom dictionary as it is considered international.

To see the United Kingdom dictionary on the list you have to change spellright.groupDictionaries setting to false. Otherwise, you’ll see only the “English” dictionary.

Settings for writings texts

VS Code is predefined to write… code. The most important tweak I applied is word wrap. I don’t like when my code is wrapped. I have this disabled for javascript etc. But while writing texts it is useful to be able to read a whole line with a single glimpse.

Here are my settings:

 "[markdown]": {
 "editor.wordWrapColumn": 80,
 "editor.wordWrap": "wordWrapColumn",
 "editor.quickSuggestions": false
  },
 "spellright.groupDictionaries": false

2. Copy & paste text to HemingwayApp editor

Hemingway tells me which sentences are too long or complicated. It also points out all adverbs and non-essential words.

Improve grammar errors with Grammarly

Grammarly works in Hemingway editor!

As a non-native English speaker, I often forget to add a/an/the articles. I make simple grammar mistakes as well. Grammarly helps me out here.

I was looking for quite some time where to use it. There is VS Code extension as well but I don’t like having too many extensions.

Adding Grammarly to my browser saved me lots of work with copying content to yet another tool. Grammarly has its own editor which is pretty good. I don’t involve it in the process as I want the process to be as easy as possible.

3. Copy content back to VS Code

After some editing and polishing I copy the text back to VS Code and publish it to some internal audience. After some reviews I start to promote content on social media.

4. Create a hero image

The last thing I like to do is to create a hero image. This is the image displayed when I publish a link to the blogpost anywhere on the internet.

I use Canva to create such images. I have created a template once and now I reuse it. I change title and add some drawing to make it unique among my other links.