Ask HN: I find writing difficult, how do I make it easy? | Hacker News Reader

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

43 pointsphekunde39 comments

When writing documentation and project proposals I struggle to write in a concise way. I find it difficult to write in a lucid way. Even after rereading and editing my docs multiple times I am not happy with the outcome. In fact I fall into dilemma on which of my edited drafts should I choose as final version.

How do I learn to write concisely?

View on HN

"A writer is someone for whom writing is more difficult than it is for other people." -- Thomas Mann, Essays of Three Decades

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/

Most of the other suggestions wouldn't work for me personally.

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.

> I find it difficult to write in a lucid way.

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.

I forgot the best tip - read Zinsser's On Writing Well, such a great book.

(A) Frame the full picture in your mind before you start to write [1, 2]. A short story: Someone once wrote a long letter to a friend, and finished it with something like "Sorry, I did not have the time to write a shorter one!" [3] I.e., it can take longer to write shorter! The reversal comes from conceptualization and framing of what you want to say, not from the actual writing itself. Use mind maps for this if that would help.

(B) Be conscious of word choice. Check even those words out in a dictionary which you think you already understand. You may soon have a refined judgment on when to check.

(C) Introduce time breaks before reading your creation for self reviews. Writing involves intense thinking which is a subject to confirmation bias. Reading your own writing a few days later will give you a flavor of what it feels like as a reader.

(D) Close the feedback loop with the actual readers, whether live or offline. Watch for the discussions that happen on the subject and see if those discussions could have been avoided by writing differently, thereby driving consensus faster.

>> which of my edited drafts should I choose as final version.

Why not have only one draft, a single working copy of the doc? :-)

See also: https://alokgovil.com/to-learn-to-write-well-read-a-lot-too/ (on my own blog)

-- Footnotes --

[1] https://en.wikipedia.org/wiki/Blind_men_and_an_elephant

[2] Improvisation also works but should be less preferable.

[3] https://quoteinvestigator.com/2012/04/28/shorter-letter/

As an academic, so a full-time writer, getting to the point of 'decent writing' took years and about 50% of my work-time so far. The key was never stopping writing (500 words per day on a weekly average) coupled with external, sometimes brutal editoring/reviewing (in this case, from my supervisors).

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.

I’m still grateful for a high school teacher that would assign a 1000 word essay and, weeks later after we’d forgotten it, hand it back and make us write the same essay in 250 words without losing the meaning of the original.

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

Wow, such a good idea!

Here are some tips/hacks/info that might be helpful:

- Use a voice recorder (step a way from the computer an dictate to yourself what you want to say--ideally while walking), then come back to the computer and transcribe what you said. You writing style will be come --- literally --- conversational. A plan/outline might be helpful to bring on your walk-a-talk to help you stay organized.

- Use dictation software like the one built-into mac OS, or the one in google docs. It's pretty good accuracy

- Use a text-to-speech software to read back what you've written, see info how to setup here https://docs.google.com/document/d/1mApa60zJA8rgEm6T6GF0yIem...

- Watch the video on this page https://documentation.divio.com/

- Think of the reader https://www.youtube.com/watch?v=vtIzMaLkCaM

Twitter.

I used to write long pendantic paragraphs without going to the point. Trying to address all possible combinations in the same sentence. Abusing passive voice and nesting sentences.

The character limitation in Twitter, forces you to think in the substance you want to convey.

It's like programming a microcontroller, it has less resources, so you need to address the limitations to have the same results.

Writing clearly and concisely is not easy, so it's quite natural for many people to find it difficult. In fact, writing woolly and verbose prose is much easier - perhaps why it's so predominant?

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/

I like to call it writing clean. You write just the subject, the verb, and the object. "Press the button. Find the file on your desktop. Delete the pointer." Do this until you feel more comfortable writing with style. Also, don't be precious about your writing. Today's writing is tomorrow's fish wrapper. Fire and forget. I wrote this, too: https://hackernoon.com/how-to-write-a-book-2065b6e807d3

Is it about the technical details or about the delivery and the writing? I find it hard to come up with the details while making a lucid narrative, usually in order to write a good narrative I really need a tight grasp on the technical details. Even then, it can be hard to figure out which thread to pull on first. Many times understanding your audience is key to making a lucid argument in a way that will convince them. That is step 1.

But it sounds like if you are wondering which draft is better that you are maybe worried about the writing aspects, such as word choice and ordering sentences / paragraphs. If so, I'd suggest maybe starting with a bullet point list or an outline with subheadings with the details. Then you can turn each point into a paragraph or sentence. Reordering will be much easier and not worrying about writing full sentences can lessen writing anxiety.

If you end up writing a really good outline, sometimes that can be even more effective and quick to read than a more long form paper.

Since you also bring up being concise (which is different from lucidity), I find it totally normal to end up cutting a 1/3rd of the text of a first draft. Edit ruthlessly; use active voice, cut out useless or random thoughts that may be interesting to you, but won't be to your reader.

Also, of course, practice makes perfect. And find a good editor.

It is difficult because your standards are higher than what you can dish out effortlessly. That's a good thing. Higher standards are the route to better work, and towards even higher standards. Make peace with never feeling satisfied!

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.

I like the ideas mentioned, here is another point you may want to consider:

How do you compose your text messages? Are you always the person sending multi-lined or even paragraph responses? Try fitting your message in one to two lines while keeping the general meaning.

Example: "Hey, what did you do at the beach today? I heard the weather was nice." ----->>> "Hey how was the beach"

The second response cut out unnecessary details and flows more naturally. I get better conversations with people following this method.

Without seeing a writing sample, it is hard to gauge how you express your ideas. Maybe you try to 'connect the dots' too much and over-explain things. Remember, you are writing to professionals. You are not training monkeys on how to do a job.

Watch this video: https://www.ted.com/talks/john_mcwhorter_txtng_is_killing_la...

Practice! Go back and rework older documents - it’s hard to edit something you just wrote. Time between writing and editing will give you perspective, and help you understand what to do better in the future.

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).

When I'm having a hard time writing a document I usually do the following:

- 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.

Some suggestions: 1) Use active voice where possible 2) As someone already mentioned, try the suggestions from "Elements of Style" 3) Have someone read it and tell you what they think you're trying to say

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

Two things that helped for me:

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.

A lot of people here have some pretty solid writing advice.

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 :)

Watch this video on the five principles of clarity https://www.youtube.com/watch?v=maKe0wQqJ0g If you focus on the clarity of your writing, it will guide you to the best way to express yourself. My company, ProWritingAid, produces lots of content for people who want to improve their writing. Our mission is to empower people to share their ideas, because lack of writing confidence can often be an impediment to sharing your knowledge and experience. Writing is a skill like anything else, and practice does make perfect. I used to be a terrible writer. Best of luck.

> Which edited drafts should I choose as my final version

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"

Strunk and White - The elements of style you can read it cover to cover, but also just come back every now and again to look at what you can further improve. I find I pick 1-2 things each major project to focus on.

Initially I focused on removing 'that' from things. Then i focused on ensuring my sentences have a single point.

Pick 1-2 things and get good at them, then move on. https://en.wikipedia.org/wiki/The_Elements_of_Style

I've been reading Ryan Holiday's book Perennial Seller, and it's great to read as a developer, and someone who is learning the importance of being able to sell.

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.

Most people forget what they learned in school and just “try to write”. Jot down some ideas, create a rough outline. Fill in your outline: introduction, point 1, support 1, point 2, support 2, conclusion, etc.

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.

Others have suggested starting with the small things - email, text messages, etc. I agree; those are good places to practice.

I've gotten a certain amount of benefit from exposing my work to trusted test readers. Sometimes that's my manager, sometimes my team. Sometimes I deliberately look further afield for readers from my target audience (e.g. people who don't already know the thing I'm writing about).

I hope this helps. Best of luck!

I've referred others to this essay on writing by pg: http://paulgraham.com/talk.html.

Also relevant:

http://paulgraham.com/useful.html

http://paulgraham.com/writing44.html

I think the hard part of writing is our fear of being wrong or not polished. We want to put together ideas and show others that we are right. The struggle leads to incoherent thoughts. We are afraid to write them down.

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.

"From time to time, I get a letter from some aspiring young writer, asking about how to write or how to get published. My usual response is that the only way I know to become a good writer is to be a bad writer and keep on improving."

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

I use to find writing hard. Then i read that is easy to write about things you hate than write about things you like or are neutral too. So now when i have to write, i start with things i hate that i want to say. Then reword it. This works for blog posts. For technical docs, i start by putting down enough info so that people will not bother me. Then i reword

I've yet to try this. I read a while back that Benjamin Franklin learned to write by picking prose he thought was good and rewriting it in his own words. He did that over and over until he felt he was good enough. Eventually he founded his own newspaper and ultimately retired very wealthy in his forties.

I found two style guides to be very helpful.

First is the Economists and the second is the plain language guide: https://plainlanguage.gov/resources/articles/dash-writing-ti...

Practice and feedback. Find someone whose writing style you admire and ask them to suggest edits to your drafts. Try to understand why they suggested those edits. Ask about any edits you don’t understand. Write more. Get more edits. Wash rinse repeat until the suggestions for major changes become rare.

When writing instructions treat the reader as if they know nothing. Write simple clear sentences. Each one should explain what the next step should be.

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.

What's the easiest thing to write about? Easy--

1) Name somethings you're interested, invested, passionate to speak about.

2) Write all you can until you're bored.

3) Read more about #1.

4) Repeat.

It's not a destination. It's a path.

You know pair-programming?

Find a less knowledgable person and do pair-documentation-writing, guided by their questions and confusion.

I am not happy with the outcome

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

I find creating an outline helps.

Delete your backspace key.

Reply on news.ycombinator.com