[HN Gopher] Ask HN: How do you approach writing documents?
___________________________________________________________________
Ask HN: How do you approach writing documents?
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.
Author : archielc
Score : 11 points
Date : 2022-05-02 19:58 UTC (3 hours ago)
| mikewarot wrote:
| 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.
| bradhe wrote:
| 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.
| iwwr wrote:
| 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 wrote:
| 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.
| sieste wrote:
| 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...
| 8note wrote:
| 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
___________________________________________________________________
(page generated 2022-05-02 23:02 UTC)