Ask HN: How do you approach writing documents?

15 points by archielc 4 years ago | 13 comments

Writing documents (design documents, one-pagers etc.) is particularly hard for me. Sometimes it's a real struggle, up to the point I cannot squeeze out a sentence for a long time. Often I start procrastinating. This happens even when I have a good background on topic / clear vision. I wonder how others in this community approach technical writing process.

mikewarot 4 years ago |

Nobody writes well written prose.

Everyone writes, then does a better or worse job of editing. Like code, prose tends to crystalize into smaller and higher quality pieces over time.

--- Process ---

Write all of your thoughts in a stream of consciousness flow, don't worry about how it looks, just get your thoughts out of your head, and into the storage medium of your choice. This frees up stack space in your brain.

Next - Iterate. Strategies you can use to help include:

Read it out loud to yourself. You'll immediately notice typos, grammatical and flow issues.

Walk away from it to gain some distance in time and space. When you come back you'll notice gaps or repetitions.

Repeat until you're happy.

doubled112 4 years ago | |

This is it.

Just toss down whatever you have. Once I realized you could start like this it was like the hurdles were all removed.

I work just like you say. Honestly, I think my beginnings are less a stream of consciousness and more a spew of garbage. Once you're done streaming or spewing, figure out what's next given the time you have.

Sometimes I stare at it. Sometimes I wander off and forget about it completely for a long time. Sometimes I do something else and come back to it. Sometimes I start a new document and try again.

Eventually it ends up something I can pass off sounding pretty decent. With some practice editing happens faster with fewer iterations. I've become better at knowing the audience too.

I won't admit to how much editing and rearranging and repeating the process this very comment took.

> I didn’t have time to write you a short letter, so I wrote you a long one.

simonblack 4 years ago |

"Often I start procrastinating." <grin> That's something we all do.

Seriously, set out the main points you want to state as a list. Then flesh those out. Then start editing (as one of the other commenters has already said). Think about what you have, maybe change the layout and edit some more.

You may need 'one version to throw away' before you come out with the final product. Very rarely will you be 'finished' when writing a document. There always seems to be just one more edit.

Don't let the fact that the document is 'unfinished' delay you if need be. Sometimes you just have to get it 'out the door', unfinished or not.

8note 4 years ago |

For something like a design, I start by writing requirements, objectives, and then drawing artifacts: sequence diagrams, data model, evaluation of how the design meets the requirmeents etc.

Those fit into templates text like everyone else is suggesting, but I start by putting in nearby the drawings "figure x shows blah blah blah" once you've got that, you can introduce what that thing is saying, and after it, you say why it should be that way, usually referencing appendix material.

Most of technical writing I find is writing more and more detailed introductions. Each time there's a header, there's also a related intro statement.

Before you get far into the doc, writing out the glossary and defining the different actors is very helpful, so you can use that language consistently

aakresearch 4 years ago |

This was once posted on HN: https://news.ycombinator.com/item?id=21289832, so give credit there, if you want.

It is like periodic table for chemical elements, singularly the one best thing about documentation that I ever read. It helped me immensely to structure the way I am thinking about documents. It starts with clear delineation of four quadrants: tutorials, how-tos, explanation and reference, and everything just clicks from there. I found that my problems usually due to subconsciously mixing them up - and setting the boundaries is very useful.

iwwr 4 years ago |

Maybe start scaffolding first. Split up the docs into standard sections: who this is for, what it intends to describe, level of detail (marketing, executive summary, runbook). Then fill in the sections at the level needed.

jjice 4 years ago | |

Agreed. I try to keep docs simple. Create headers for different sections and give yourself a TODO for what need to go there. Then it's just writing.

Aromasin 4 years ago |

As others have mentioned, be sure to write bunch of headers of what you're actually going to write, then work from there. Start by giving each section a title, then each sub section, then each paragraph. Below each title, give a one line summary of what you're going to write about in each part. From there, you're simply filling in the gaps. This method improved my productivity with writing 10-fold.

sieste 4 years ago |

Work hierarchical, at different and clearly defined levels. Start with writing down the big picture (TOC, chapters, section headings), refine until happy. Then move to next level (subsection, paragraphs) and briefly summarise what points you want to make ("topic sentences"). Then move on to expanding the topic sentences to paragraphs of multiple sentences, without worrying too much about individual words and phrases. Move things around until the narrative is coherent, and you might have to go back to moving things around at the paragraph level. Once you're happy with how the content is organised in sentences, only then polish your writing at the individual word level. The important thing is to always be clear at what level you're working, ie, don't start working at paragraph level and fix typos at the same time.

I also found Jordan Peterson's essay writing guide [1] useful, not just for academic writing.

[1] https://jordanbpeterson.com/wp-content/uploads/2018/02/Essay...

bradhe 4 years ago |

It’s a skill just like coding. It takes time to figure out what’s important and what isn’t, so the best thing to do is just dive in and make mistakes.

After a while, you find patterns that make it more effective and easier.

nicbou 4 years ago |

You need a plan!

I always start with a nested list of what I want to communicate. I refine the order and completeness of this list for a bit, usually over breakfast.

Once you have that, you just flesh out each point one by one.

smackeyacky 4 years ago |

Use outline mode of your word processor. Write all the headings, then jump around filling it out.

Parker_Powell 4 years ago |

I approach writing documents by being clear about the goal and message for my audience. My first step is to research the subject I'm writing about, so that I can be sure I'm prepared to convey the information clearly and concisely. Then I brainstorm different ways I can accomplish that goal based on my knowledge of my audience's expectations. Once I've settled on a way forward, I outline my thoughts and write a draft. As I work on the draft, I stay aware of the audience's needs and how best to meet them. Finally, after reviewing the document several times and getting feedback from others, if possible, I polish it up!