
Ask HN: How to write a good technical article? - wizardofmysore
I&#x27;ve been trying to come up with a good process to write technical articles but they never seem to get over a couple of views.<p>It feels like the ideas are great but the writing isn&#x27;t.<p>What&#x27;s a step by step process to come up with a great article?<p>How do I learn to write well?
======
philipkiely
I wrote an entire book on this topic: Writing for Software Developers [0]

Here is my step-by-step process once you have an idea:

1\. Identify your audience and the assumptions you're making about them. Who
is reading this tutorial and why?

2\. Write an outline that hits the key points to figure out what order to
present the information.

3\. Build "pylons:" code blocks, images, and other concrete aspects that
readers can use in their own work.

4\. Connect these pillars with explanation and intuition. Focus on "why," let
the code blocks handle "how."

5\. Edit by reading the article out loud. Make your language conversational.
An approachable article reads like a conversation with a senior co-worker or
professor.

[0] [https://philipkiely.com/wfsd](https://philipkiely.com/wfsd)

------
noble_pleb
Brainstorming is the key, take each one of your ideas and scrutinize it from
all perspectives. Ask the journalists' questions (how, what, why, when, etc.)
and read as much as possible. If its a technology or programming language you
daily dabble in, the content should come naturally to you.

As for the problem of having the content all in your head but still being
unable to put it down on paper (or laptop screen), I can understand and
empathize with that problem! Writer's block can be due to many reasons but the
best way to solve it is to just have a ritual of just sitting on your desk
daily at a stipulated writing time. Even if writing doesn't come to you in the
beginning, it will eventually flow as you make this a habit. In many trades,
success is just a matter of showing up, its the same about writing.

------
bruce511
The key to writing well (code or text) is to understand that most of what you
write must be discarded.

In other words, it's not good writing that is the secret. It's good _editing_,
and good _re-writing_.

For me my process is to a) write down my thoughts in a more-or-less random
order - just at a high level. Just a sentence or two.

b) organize those thoughts so they make sense "in order". Help to make those
thoughts into a narrative that flows from one point to the next.

c) expand on each thought.

d) wait a bit, then re-read each bit. Edit where necessary.

e) re-read the whole - edit as necessary. (I find reading it aloud can help.)

f) loop to (b).

The more times you loop, the better the result. Like with code, it's not about
how fast you write that matters. It's how elegant and polished the result that
is important.

Refactoring 100 lines into 10 is painful, but the result is better. Deciding
what to leave _out_ is more important than what to leave in.

Think of it like this - the writing part should take 10% of the time. The
editing, and improving should take 90% of the time.

Lastly come back to the writing a month later, or 6 months, or a year, when it
isn't so fresh. Read it again. And, as an exercise, edit it again. Learn from
that for the next thing you write.

------
FlashBlaze
Here's how I do it.

1\. Note down the problem you're facing in your current project and search
online for the solution.

2\. If you find the solution, read it and try to implement and understand it.
If you understand it and think "oh, I could have explained it better" create a
rough draft.

3\. If you don't find a solution, but rather parts of it from different
resources, list down the sources and go from top to bottom on how to combine
and implement these.

4\. Now the writing part. I first introduce the problem I faced and resources
I found and sort of explain how they didn't fit my need and what I did to
solve my problem and how to combine these.

5\. I then create a demo project for the same and go step by step with the
accompanied code, some pictures/videos and a sprinkle of humour(which I just
started doing tbh).

6\. Create a first draft with this and read it once or twice to see what you
can reduce to make the article more succinct.

7\. If possible, give it to your friends to read and ask for their opinion on
grammar, pacing, etc and modify it accordingly.

8\. Publish it when you're satisfied.

Hope this helps.

------
eris202
I will say a good article must contain at least 350 words When writing an
article make sure you explain the topic of your post a not diverting to other
topics And I suggest you using Grammarly because nobody is perfect

