Re:Ask HN: How to write a good technical article?
by philipkiely on Sunday June 21, 2020 @10:18AM
(#23592148)
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.
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