Ask HN: I find writing difficult, how do I make it easy?

Practice will help. Reading other people's writing will also help - find examples of writing you like.

Most product documentation is abysmal. Here is a random, but reasonably good example: installation instructions for Craft CMS. It assumes some technical knowledge, but the description is fairly clear: https://docs.craftcms.com/v3/installation.html

I find the 10 tips for clear writing at the following link very helpful:

https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/

You don't need to listen to the podcast (unless you want to) at the top of the linked page. Scroll down the page and you'll find a short description of each of the following tips:

1. Establish ‘The Point’

2. Write it like you’d say it

3. Don’t try to sound clever

4. Show the thing

5. Know that you are not your writing

6. Share your work

7. Read (poetry in particular)

8. Never start with a blank page

9. Know when enough is enough

10. Stay human

Edit: another example I wanted to share of clear writing. The NHS (National Health Service in the UK) has an excellent A-Z of health conditions website: https://www.nhs.uk/conditions/

I have always liked how clear, straightforward and simple the entries are without the information being 'dumbed down' in any way. Here is a random health entry (on epilepsy) to illustrate: https://www.nhs.uk/conditions/epilepsy/

Then it's not finished except possibly in the "out of time" sense.

Reading about writing will help too. “The Elements of Style” is great, as is Stephen King’s “On Writing” (for the latter, ignore the parts focused on fiction).

Writing well is hard. You should struggle to write well. The fact that just about everyone can write makes it even harder.

https://www.tsowell.com/About_Writing.html

So the first hurdle of writing is to overcome our fear. We may be wrong. But we can write it down and present it. If we are wrong, we can admit it. We'll write better as a result.

1) Read a lot. Read different styles. Read the newspaper, read fiction, read blog posts, read history textbooks. Read lots of things. The diversity of styles will give you ideas on how different things can be communicated well in their own context.

2) Analyze what you read, just a little. I started with just asking myself "who is the intended audience of this writing?" Asking a consistent question in your analysis will make comparison easier. It will also help you think through your own writing: "am I writing this for the marketing person who is going to try to sell it? am I writing it for the coder who has to install it? maybe I need two separate documents for each of them?" That thinking about writing will help you analyze and adapt your own work.

- Go back to basics: Review what an introduction, body, and conclusion should have (and what they shouldn't). This of course will depend on the kind of document, since the structure and content of a research paper, a proposal, or an essay will be different.

- Make an outline: Lay out the different ideas in sentences. At some point, you will have all you need and you will just need to connect the sentences to create paragraphs and then sections. This specifically helps me to write concisely, as my document is a flowing outline.

- Revisit: Finally, if I have the time I like taking a break and revisit (even if it is the next morning). This gives me the time to come back with fresh eyes and spot the parts that do not flow, need more detail, or are redundant.

I've noticed that if I struggle creating the outline, it's because I don't understand well yet what I am trying to write.

Also relevant:

http://paulgraham.com/useful.html

http://paulgraham.com/writing44.html

For documentation copy the structure something that does something similiar and start filling in.

Proposals have a structure. Copy it and try to fit in your ideas around it.

Reworking old documents is too boring. Reading The Elements of Style isn't going to happen.

Focus on writing stuff you like to write about. I like writing about Apache Spark so that's an easy topic for me to write blogs: https://mungingdata.com/

Write about what you're interested in. That'll help you level up for when you need to write about boring stuff.

As others have mentioned, deliberate practice is really the only ticket. I bet you write a ton of email, start practicing there. Or your text messages. The more you do it the more you'll discover things that work for you. Also accept that it takes a preposterous amount of time to write well. Reading books on the subject of writing by writers can be comforting in that regard. I'm thinking particularly about Steven King's "On Writing" and "Draft No. 4" by John McPhee.

Also, reading high quality writing is worthwhile. If you mostly read on the internet and you pick-up a really well written book the contrast can be startling.

One unconventional source of great writing I recommend is US Supreme Court opinions [1]. I find almost every single one to be very well written.

[1]: https://www.supremecourt.gov/opinions/

Something you can do to passively improve your writing is to read. Honestly read anything you're interested in, but if your goal is to really improve a certain type of writing, read that. Then read something else :)

Honestly the way out is to just publish stuff and get feedback. You'll see there's not an army of jerks waiting to tear you apart and instead that most people are supportive. If there are an 'army of jerks' its only because you've gotten sufficiently popular ;)

Also, dirty little secret. We all edit after the 'final version' too. Even a printed book there are editions. Heck I wrote a book 4 years ago, and looking back I know more now. I tell people "that was a signpost of my knowledge 4 years ago"

This works great for documentation. Ask the 5 W’s. Who will read this? Why? When? How often? What are they trying to achieve?

If you’re editing and a sentence doesn’t fit your outline, pull it out and either it’s not important or you need to update your outline.

I think external editing/reviewing is key. A sentence you've reworked ten times sounds perfectly reasonable to you because you've read it hundreds of times, but to someone else it may unintelligible garbage.

I'm not sure how your different edited drafts differ. Are they details? For me I first sit down and think of the 'one' story I want my data to tell, from there flows only one single possible draft.

The big take-away so far, is that it is all about editing. Get something down, and then work it again and again. When you write a sentence, that's just the beginning, not the end. If you take that approach, it may help.

I now view some of my writing as "wordsmithing". Sure, I write, but then I re-write and review, and get feedback, etc. etc.

There are two techniques that work for me. Perhaps they will help someone.

First, the empty page. The empty sheet is the hardest to tackle. I dump out the main points I want to convey, in no particular order, and I am often surprised at the narrative arc taking shape. There's content hidden inside ones brain that's occluded by the part that's policing the written style. Concentrate on first getting it out in the form of bullet points, small funny phrases, headlines, etc. You could use powerpoint to restrict yourself from having to think in terms of long sentences. Then you look back and see what your brain has conjured up.

Second, reviewing. When reviewing a draft, for each set of lines that focus on one idea or concept or theme, write a very short description (4-5 words) of the idea on the margin. Now, start from the top and only read the margin annotations. That gives you a feel for the narrative arc. Give an entire para to an idea if it spans a few sentences.

When you have something to say, write. Then set it aside until you have time to improve it. Then publish.

So does everyone. It's like with "clean code" - no-one can write clean code. You write dirty code and keep editing it until it's clean. It's easy to see someone else's 20th draft and think you can't write as good as them. Neither can they.

It's like everything, you're bad when you start doing it, and you get better at it as you do more of it.

> Even after rereading and editing my docs multiple times I am not happy with the outcome.

How many times is "multiple times"? Doesn't sound like too many. A few dozen times wouldn't be unusual among writers. i.e. Editing every day for a month.

> In fact I fall into dilemma on which of my edited drafts should I choose as final version.

So just have one version. If a change doesn't make a sentence better, don't make that change. Sure, sometimes you can't decide which of 2 versions of (say) a sentence is better. So choose the simpler, the one with less words, the less show-offy one, the more direct. Also, put it aside for a few days or a week or two and read again. Choices like that will be obvious again after you get some time-distance.