Recently, a colleague asked me about writing technical articles.

[D]o you have any tips for feedback and writing cycle? When and how often should I be asking for feedback? Writing the scripts for each chunk of the article vs creating scripts after receiving all feedback?

I’ve written a bunch of articles. Some of them got pretty popular.

Writing is almost never a solo work. How do you ensure that every relevant member of your team reviews the content, without bogging you down in endless reviews?

My process is below. All of this assumes you’re writing the article in Google Docs (or similar collaborative software), and make it accessible and editable by all your colleagues. This might be scary at first (most people prefer writing completely solo and only sharing with others when the work is almost done). But it’s the best way.

Figure out who the “early” stakeholders are

Hopefully it’s just 2-4 people, subject experts, not a full committee, and not (yet) editors. (I highlight this because just this week I’m releasing an article with seven reviewers, and it’s a major pain.)

In your early stakeholders, you want a good mix of Those-Who-Know (typically the software engineers behind the code) and Those-Who-Can-Communicate (typically more senior people engineers, PMs, DevRel).

Write a short “principles” section

It is there to set expectations for the reviewers. It’s not going to be part of the article itself.

This section addresses questions about the scope and the vision of the content.

Is this article meant for beginners? Is it meant to be a quick read? Is it more of a guidepost? Are you using some framing device that might need explaining? Are you knowingly avoiding a topic for some good reason? What are the goals of the article? What do you expect people to do after they read it?

You don’t need to answer all these questions for every article.

Write a rough outline

Just a bullet point list. What comes first, what comes next. What points do you want to make?

Ask for outline LGTM

Ask the early stakeholders to review and specifically ask for LGTM (“Looks Good To Me”; basically, a rubber stamp). Set a deadline for them. If someone is a little late, that’s okay, but don’t wait forever. Once it’s past deadline, it’s fair to just say “sorry, too late”.

Start writing

When you have an LGTM from everyone on the outline, start writing.

Actually, scratch that. If you have any free time at all, at any point during this process, start writing parts of the article or even the whole thing. You’ll learn the most by actually writing. You can plan for 200 years and never really see all the little things that come up only as you start putting words together into sentences and paragraphs. Writing is hard. We all have a tendency to try and avoid it via planning or postponing, but that’s folly. Be prepared to delete anything you write at this stage. Don’t get emotionally attached to your writing (just yet).

Finish the first draft

It can be rough, with images missing, paragraphs with “TODO” items, etc

Do the same loop as before, with LGTMs. Maybe pick only a subset of the reviewers, or a completely different group.

Iterate

You can iterate the draft several times.

At some point, you’ll have a final draft

The final draft is something that should be structurally very similar to what you publish. You can invite more people to review. Especially editors (tech writers). If someone asks for a major rewrite at this stage, then a) you’re in trouble, and b) you should have asked them for review earlier, OR c) they’re being a little silly and you can ignore them. (This is why it’s good to have good subject matter experts AND good communications people in the early stakeholders group.)

At the final draft stage, your content has already been LGTM’d several times by people, so basically you only need a stylistic LGTM from a writer. But it’s good to circulate the final draft more broadly — little things always slip by unnoticed.

Congrats, you’re ready to publish!