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://github.com/robotichead/NearBeach) for a few years now, and I still do not know how to write it's blog posts or documentation. A good example of my skill would be the following links;<p>- Documentation https://nearbeach.readthedocs.io
- https://nearbeach.org/index.php/2020/03/10/nearbeach-beta/<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
This is the best writing advice I ever received:<p>"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."<p>It's a quote by George Polya.<p>The paragraphs you have written don't seem unprofessional to me.<p>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.<p>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".
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.<p>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<p>[1] <a href="https://freelancemag.blogspot.com/2019/11/write-write-and-write-should-be-your.html" rel="nofollow">https://freelancemag.blogspot.com/2019/11/write-write-and-wr...</a>
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.<p>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.<p>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.
“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.<p>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.
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.<p>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.
Great question. Writing skill is generally underdeveloped in engineers, and it's absolutely worth getting good at.<p>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.<p>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.<p>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.
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.
> I still do not know how to write its blog posts or documentation.<p>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.<p>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.<p>Either individual alone will easily flounder or write prose with a bad UX.
1. Practice a lot. Just get as many words on paper as possible.<p>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 <a href="https://www.reddit.com/r/KeepWriting/" rel="nofollow">https://www.reddit.com/r/KeepWriting/</a> and get feedback on writing you are comfortable releasing to the public.<p>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.
I find the 10 tips for clear writing at the following link very helpful:<p><a href="https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/" rel="nofollow">https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/</a><p>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:<p>1. Establish ‘The Point’<p>2. Write it like you’d say it<p>3. Don’t try to sound clever<p>4. Show the thing<p>5. Know that you are not your writing<p>6. Share your work<p>7. Read (poetry in particular)<p>8. Never start with a blank page<p>9. Know when enough is enough<p>10. Stay human
> ... have re-written multiple times from scratch.<p>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.
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 :)
Get the book called Everybody Writes by Ann Handley: <a href="https://www.amazon.com/Everybody-Writes-Go-Creating-Ridiculously/dp/1118905555" rel="nofollow">https://www.amazon.com/Everybody-Writes-Go-Creating-Ridiculo...</a><p>It’s a quick read that will really help you.
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)<p>several people say to avoid passive voice (I'd agree, but don't believe me, see some examples of this)
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.
Didn’t look at your link, but the above is fine. Concise, organized. It’s OK.<p>Advice: Practice. Edit.<p>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.
There are a couple "frameworks".<p>Situation>Problem>question>Answer<p>There is an SPQA for both YOU and your target audience.<p>What's the problem?
Why is it hard?
What's the solution?
In one sentence, this is your main idea.<p>Recipe for a five paragraph essay or blog post:<p>Paragraph 1
1. Main idea
2-4. Supporting points
5. Conclusion<p>Paragraph 2-4
Reiterate supporting points + issue, cause, solution(s) and supporting points<p>Paragraph 5
Conclusion + supporting points
Transition: New ideas, concepts, studies to conduct or angles
Separate out the phases of the writing process. Do one <i>then</i> the next in explicit phases:<p>## 1. Get ideas out.<p>A successful result at this stage looks like a pile of messy clay.<p>Set a timer and just keep typing for 20 minutes pomodoro-style. Maybe download <a href="http://otter.ai/" rel="nofollow">http://otter.ai/</a> and talk to yourself while you exercise.<p>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.<p>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.<p>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.<p>## 2. Find the structure of the ideas.<p>A successful result at this stage looks like a bunch of topic headings in a layout that makes sense to you.<p>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?<p>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.<p>Either create an outline or directly push your clay into that shape.<p>## 3. Notice holes and fill them.<p>A successful result at this stage looks like text that flows in a way that makes sense to you.<p>If you notice that there is an image you need, sketch it on paper or whiteboard or <a href="https://jspaint.app/" rel="nofollow">https://jspaint.app/</a>. You can hire a professional later if that matters. Do a few pomodoros where you repeat step 1.<p>To get better at this, play the board game Concept[1].<p>## 4. Create a good User Experience out of words.<p>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.<p>Follow the advice from Style: Towards Clarity and Grace
<a href="https://sites.duke.edu/niou/files/2014/07/WilliamsJosephM1990StyleTowardClarityandGrace.pdf" rel="nofollow">https://sites.duke.edu/niou/files/2014/07/WilliamsJosephM199...</a><p>Edit your work multiple times.<p>[1] <a href="https://www.youtube.com/watch?v=XiB9BvEpYFE" rel="nofollow">https://www.youtube.com/watch?v=XiB9BvEpYFE</a><p>[2] <a href="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/" rel="nofollow">https://psychologyhub.co.uk/the-working-memory-model-central...</a>
Try to write in E-Prime style.<p><a href="https://en.wikipedia.org/wiki/E-Prime" rel="nofollow">https://en.wikipedia.org/wiki/E-Prime</a>
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".<p>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."