
Ask HN: How can I improve my writing - robotichead
Hello Hacker news,<p>I have trouble writing. It is hard to get ideas out of my head onto paper. For example this paragraph I have re-written multiple times from scratch. Many of the times I do not know where to start, or how to express a simple idea effectively on paper.<p>I have been working on my side project NearBeach (https:&#x2F;&#x2F;github.com&#x2F;robotichead&#x2F;NearBeach) for a few years now, and I still do not know how to write it&#x27;s blog posts or documentation. A good example of my skill would be the following links;<p>- Documentation https:&#x2F;&#x2F;nearbeach.readthedocs.io
- https:&#x2F;&#x2F;nearbeach.org&#x2F;index.php&#x2F;2020&#x2F;03&#x2F;10&#x2F;nearbeach-beta&#x2F;<p>My first opinion of my writing skill is that it does not flow and seems very UN-professional.<p>Thank you for your advice
======
Gormisdomai
This is the best writing advice I ever received:

"The first rule of style is to have something to say. The second rule of style
is to control yourself when, by chance, you have two things to say; say first
one, then the other, not both at the same time."

It's a quote by George Polya.

The paragraphs you have written don't seem unprofessional to me.

The best way to improve the "flow" of ideas when you write is to have a clear
idea of where one idea ends and the other starts.

For longer pieces of writing, consider intentionally "signposting", by saying
meta things like "now that I have explained X, I can set out why Y is so
interesting".

------
el_programmador
The trick is to go and sit at your desk regularly until writing comes on its
own. Its all right if you don't write, but you're not supposed to do anything
else. And write anything you feel like ignoring grammar, content quality or
even subject. Given enough time, practice will ensure that you'll become a
good writer.

Link to article (shameless plug)[1]: Write, Write and Write should be your
Mantra - Procrastination is the Writer's only enemy in 90% of cases

[1] [https://freelancemag.blogspot.com/2019/11/write-write-and-
wr...](https://freelancemag.blogspot.com/2019/11/write-write-and-write-should-
be-your.html)

~~~
robotichead
Thank you :)

------
sjperez
The fact that you're asking about how to improve your writing is a fantastic
first step. I think writing is the most undervalued skill in most professions.
No matter what your job is, writing is part of it. That very much includes
technical and scientific jobs. So kudos to you for even thinking about this
skill--it's one that many people ignore.

The best book on writing that I have read is On Writing Well, by William
Zinsser. It's short and very accessible. Zinsser does a great job of laying
out why writing is so hard and how to tackle everything from fiction writing
to non-fiction technical writing. You can finish the book in a weekend of
leisurely reading and come back to it as often as you like.

Zinsser's main point, which I agree with wholeheartedly, is that great writing
is really about great re-writing. Edit mercilessly, remove unnecessary words
and phrases, and focus on getting your point across in a clear manner. Remove
jargon wherever possible. If you take the time to re-read and re-write your
work several times over, you can't help but create something better than you
started with.

------
ekr
My impression is that maybe you worry a bit too much about it. Performance
anxiety/stage fright/etc. This doesn't help of course, by making it more
difficult to have a clear head.

As long as you're getting your point across, everything is fine. It will
naturally improve in time with practice, although I can't see any problem with
your current way of writing.

------
CodeWriter23
“Problem Solving Strategies for Writing” by Linda Flower is the only textbook
I kept from my brief community college experience. It provided a good
foundation that approaches writing from a design perspective.

That book may help, but it sounds to me like you suffer from perfectionism.
That may be the area you want to investigate for self-improvement.

------
mapster
Read Steven Kings book ‘On Writing’ for starters. One point he emphasizes is
in order to write well you have to read A LOT.

------
mshron
Great question. Writing skill is generally underdeveloped in engineers, and
it's absolutely worth getting good at.

Based on your other comments, you're already starting with drafting, which is
great. The next step is to learn to revise well so you feel more comfortable
with your early attempts and don't need to toss them out.

The book _Style: Lessons in Clarity and Grace_ by Williams and Bizup is about
how to rework a draft into something more coherent. They talk about revising
sentences, and paragraphs, and then whole structures to be as coherent as
possible.

Once you have a mental model for how people read, and what makes reading
easier or harder, it's easier to get into the habit of writing and revising.
Then you get stuff out of your head and revise it until it's in a form you're
happy with. Rinse and repeat.

------
atmosx
There are many lectures on the topic by Pinker. I would start there. You can
find quite a few on YouTube. He also has a book, but haven’t read it yet, I
bet is good though. It’s a modern version of “Elements Of style” which is the
classic writers handbook for English.

------
afarrell
> I still do not know how to write its blog posts or documentation.

Honestly, I've often found that writing documentation alone is a bad use of
time. If it wasn't written as part of design or development, the first draft
of documentation is always going to suffer from the problem of bridging the
gap between knowing the system well and knowing what a knowledge-lacking
reader needs.

I submit to y'all that docs should almost always be a pair-programming
exercise between a developer who is highly knowledgable and a developer as
close to the target audience as you can get. There are plenty of more junior
devs on codementor.io or /r/learnprogramming who can help.

Either individual alone will easily flounder or write prose with a bad UX.

------
abdullahkhalids
1\. Practice a lot. Just get as many words on paper as possible.

2\. While reading writing books can be helpful, critical feedback will help
far more. Either get someone in your organization to give feedback on your
professional writing, or get a friend to critique your side project writing,
or go on a subreddit like
[https://www.reddit.com/r/KeepWriting/](https://www.reddit.com/r/KeepWriting/)
and get feedback on writing you are comfortable releasing to the public.

Remember, you don't have to take everyone's feedback. But listen to it, and
use it to learn how to critique your own writing.

------
open-source-ux
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/](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

------
codingdave
> ... have re-written multiple times from scratch.

It is the "from scratch" part that is troublesome. Most writers don't write
perfect copy on their first attempt. So to get rolling, just get the words
out, and don't expect it to be great. Then start refining it. Don't throw it
out... just improve. Simplify the wording. Remove unnecessary words and
phrases. Change the order of sentences. Keep iterating until you are
satisfied. And have patience with the process.

~~~
robotichead
I throw out stuff because it does not either make sense or flow for me. Or I
feel it is not the best way to start a paragraph/essay

~~~
vulcan01
If it doesn't flow, try rearranging your thoughts to make them flow. Throwing
stuff out isn't a great idea most of the time :)

------
vulcan01
Personal experience here, not sure whether this will help. I struggled with
writing until I realised that not all writing has to be professional/formal.
Casual writing is usually fine. Writing how you speak is also fine. Over time
I got more comfortable with expressing my thoughts, and that's when formal
writing became easier :)

------
marmot777
Get the book called Everybody Writes by Ann Handley:
[https://www.amazon.com/Everybody-Writes-Go-Creating-
Ridiculo...](https://www.amazon.com/Everybody-Writes-Go-Creating-
Ridiculously/dp/1118905555)

It’s a quick read that will really help you.

------
eldacila
I'd say focus on making things clear and simple. Use period (.) more often,
use less commas. Also write first, then edit for clarity. But don't re-write
from scratch. The Easy Approach to Requirements Syntax attempts to fix some
problems with "normal" system requirements (and they used those for automotive
and I think aviation systems, so if they made progress, you know it's real),
give it a read (focusing on the problems they are trying to solve, and see if
that applies to your writing)

several people say to avoid passive voice (I'd agree, but don't believe me,
see some examples of this)

------
davidajackson
Read The Elements of Style. Then pick a few writers that enjoy and try to
write something similar. Steinbeck, Hemingway... whatever you like best. It's
like transcribing music; you'll learn as you go.

------
Kaibeezy
Didn’t look at your link, but the above is fine. Concise, organized. It’s OK.

Advice: Practice. Edit.

Suggestion: Take an intro to journalism class. Got to be a million of those
online right now. Write, write, write. Edit, edit, edit, edit, edit.

~~~
robotichead
Thank you :) I did spend a while editing and completely re-writing sections

------
tracer4201
Write in the active voice, avoid complexity in words and sentence structure.
Don't try to use complex grammar or fancy words – it's fluff. A book I highly
recommend is "On Writing Well".

Most important advice is to write and write often. Give it time and you'll not
only get better at writing but you'll realize that writing forces you to have
clarity in thought. You'll quickly become aware that "I thought I knew X but I
don't know details A, B, or C and need to go dive deeper into these."

~~~
zimpenfish
> "On Writing Well"

Although note that some professional linguists consider the book to be
"prescriptivist poppycock".

[https://languagelog.ldc.upenn.edu/nll/?p=18345](https://languagelog.ldc.upenn.edu/nll/?p=18345)

------
kaa2102
There are a couple "frameworks".

Situation>Problem>question>Answer

There is an SPQA for both YOU and your target audience.

What's the problem? Why is it hard? What's the solution? In one sentence, this
is your main idea.

Recipe for a five paragraph essay or blog post:

Paragraph 1 1\. Main idea 2-4. Supporting points 5\. Conclusion

Paragraph 2-4 Reiterate supporting points + issue, cause, solution(s) and
supporting points

Paragraph 5 Conclusion + supporting points Transition: New ideas, concepts,
studies to conduct or angles

------
afarrell
Separate out the phases of the writing process. Do one _then_ the next in
explicit phases:

## 1. Get ideas out.

A successful result at this stage looks like a pile of messy clay.

Set a timer and just keep typing for 20 minutes pomodoro-style. Maybe download
[http://otter.ai/](http://otter.ai/) and talk to yourself while you exercise.

If you really feel stuck, then imitate Test Driven Development: Write a
question. Then write an answer. Then write a question that answer raises. Then
write an answer. Then write a question like "How can you be so sure of that?"
then write an answer. Unlike TDD, don't try too hard design, just keep that
cycle going. Just keep typing.

Question Driven Drafting like this is a one way to get words on paper even if
you are currently feeling despair or self-hatred or confusion: Explicitly have
a debate with your self-doubts. Be sure to do some physical exercise to clear
your mind after that sort of thing though.

As humans, we are socially motivated to communicate. All of these techniques
aim to imitate that. However, you might find that the most helpful thing is to
teach someone or to get on an an internet forum and pontificate.

## 2. Find the structure of the ideas.

A successful result at this stage looks like a bunch of topic headings in a
layout that makes sense to you.

Look through them identify the "why". What situation does someone come to your
writing with? What do you want someone to walk away from your writing with?
Why would they be motivated to learn that?

Write section headings to form your ideas into either a pyramid or a Hero's
Journey or some other traditional structure that will help your brain "chunk"
them.

Either create an outline or directly push your clay into that shape.

## 3. Notice holes and fill them.

A successful result at this stage looks like text that flows in a way that
makes sense to you.

If you notice that there is an image you need, sketch it on paper or
whiteboard or [https://jspaint.app/](https://jspaint.app/). You can hire a
professional later if that matters. Do a few pomodoros where you repeat step
1.

To get better at this, play the board game Concept[1].

## 4. Create a good User Experience out of words.

A successful result at this stage looks like a text which is well structured
to introduce relevant ideas into the Verbal Loop[1] of the reader's Working
Memory in an order that "chunks" often enough that it doesn't OOMkill or
having broken links.

Follow the advice from Style: Towards Clarity and Grace
[https://sites.duke.edu/niou/files/2014/07/WilliamsJosephM199...](https://sites.duke.edu/niou/files/2014/07/WilliamsJosephM1990StyleTowardClarityandGrace.pdf)

Edit your work multiple times.

[1]
[https://www.youtube.com/watch?v=XiB9BvEpYFE](https://www.youtube.com/watch?v=XiB9BvEpYFE)

[2] [https://psychologyhub.co.uk/the-working-memory-model-
central...](https://psychologyhub.co.uk/the-working-memory-model-central-
executive-phonological-loop-visuo-spatial-sketchpad-and-episodic-buffer-
features-of-the-model-coding-and-capacity/)

~~~
robotichead
Thank you

~~~
afarrell
I've updated my response a bit.

------
9wzYQbTYsAIc
Try to write in E-Prime style.

[https://en.wikipedia.org/wiki/E-Prime](https://en.wikipedia.org/wiki/E-Prime)

