What's your favorite bit of writing advice?

What is the best writing advice you ever received? Or, if not the best, what's your favorite bit of writing advice?

Comments

[Michael Tharrington]

I always loved the phrase "show, don't tell"... it's described really well in this Wikipedia entry:

Show, don't tell is a technique used in various kinds of texts to allow the reader to experience the story through actions, words, thoughts, senses, and feelings rather than through the author's exposition, summarization, and description. It avoids adjectives describing the author's analysis, but instead describes the scene in such a way that readers can draw their own conclusions.

I think it's interesting in the context of writing posts with code, because in dev posts you're likely often showing code while also telling what it does. Just to say that I think that's absolutely okay and don't think that runs counter to the phrase.

Now, if someone was to write out a highly performant code block and tell us right below it that it's good and highly performant, that would kinda break the show, don't tell rules... instead, I'd suggest to the writer that they show us how they measured the performance (perhaps with some sort of benchmark test) and outline some of the specific benefits it brings folks.

[Matt Ellen-Tsivintzeli]

The best advice I've received is to read it out loud.

If it sounds weird when you say it, you should edit it to sound better.

[Michael Tharrington]

Yes!! I'm so glad you mentioned this one... I had left a comment on @maddy's post "Tips For Your Next Pair Programming Interview" as they had given out the excellent tip to "Think Out Loud" for paired programming. Actually, that's kinda what triggered me to write this post! 😀

[Dan Walsh]

I live by this! A previous boss passed on this nugget of wisdom to me. What’s interesting is that when reading back something you wrote, if you missed a word like a conjunction, your brain tries to automatically “fill the blank” as you read. So if you read carefully and slowly, you’ll more readily find these gaps and fix them.

[Joe Mainwaring]

• Writing is a talent developed over time, practice makes for perfect. The quality and thoroughness of my content today comes from 18 years of authoring blog posts and technical documents
• There is little difference between technical documents you may write as a developer/engineer and a blog post. I routinely re-share internal documents I’ve authored, after stripping out all identifiable and proprietary information.
• Have a purpose for why you author content. Perhaps it’s to contribute back to the community, or it could be as a portfolio piece to showcase your competencies, but know why you’re spending the time publishing content online. For myself, I contribute to public discussion as a tool for career growth.
• There are two ways to author content: by what you want, or what you think the audience wants. I was never good at the later so I stick to the former.
• Drafts are both a valuable tool and graveyard, use it freely but set time aside periodically to clean things up.
• Your audience has a limited attention span, scope your content and narrative in a way that’s time-efficient.
• Organize your content using headings. H2, H3, H4, etc are your friends.
• Rich Media is a better medium for getting attention, but written content has better reusability. Being able to copy and paste technical snippets like CLI commands or application code is vital when engineers need to use a process within their own context.
• A quality piece of authored content will likely contain numerous links that serve as both referral mechanisms (linking to the vendor website) and citations (code samples, docs, white papers) to support the narrative.
• Learn your computer’s tools for capturing screenshots or recordings. If you don’t have these tools, a Google search should provide you with options.
• Annotating screenshots is a very effective way to clearly communicate repeatable steps you want the reader to follow
• Most importantly: IGNORE THE TROLLS. Engage by trying to steer the conversation in a constructive manner, but don’t waste your time trying to change a critic’s mind. Just ignore or block at that point.

[Michael Tharrington]

So many good bits of advice here, Joe! Appreciate ya chiming in.

And this bit is my favorite:

Most importantly: IGNORE THE TROLLS. Engage by trying to steer the conversation in a constructive manner, but don’t waste your time trying to change a critic’s mind. Just ignore or block at that point.

Absolutely! 💯

If they are pestering you here on a DEV post, don't hesitate to hide their comments and block them... and please, please, please report'em to us so we're alerted to step in and get your back!

[Michael Tharrington]

Ooooo, I really like the note-taking idea!

I remember reading that Hunter S. Thompson would practice prose by typing out The Great Gatsby.

I also really like the idea of writing contributing to a larger conversation... really so much of art is like that. I see it in how groups of people latch onto styles of music or painting; they're using established ideas and finding their own place in them. I think sometimes people are kinda doing it without necessarily realizing it; they're just absorbing culture and reacting to the present. However, you can often tell when someone is well-versed in a particular conversation and aware of the many different roads and side streets that conversation has taken. To follow that analogy (haha, I know who I'm talking to here 😉), it's rare that you're paving a brand new road when talking about an idea; being aware of those who have traveled down the same road, the maps they've drawn and places they arrived at (conclusions they've come to) can really help you to navigate that road.

[Kasper Andreassen]

When working with SEO-content:

Write for humans, optimize for machines

For writing in general, it's just to write something down - don't get stuck overthinking. The actual content can be improved and optimized afterwards. Related to @jmfayard says about "shitty first draft".

[Michael Tharrington]

I really like both of those!

I love your advice around how to best handle working with SEO content. I do think that sometimes we get sucked into strange patterns like overloading an article with specific terminology because we think it's more likely to rank higher in searches. It's good to remind ourselves to keep our human audience front of mind!

[Jean-Michel 🕵🏻‍♂️ Fayard]

Anne Lamott's concept of shitty first draft to overcome perfectionism

canvas.umn.edu/courses/213694/file...

[Erin Bensinger]

This advice saved me many, many times during my undergraduate English degree:

A first draft doesn't have to be any good, it just has to exist.

[Jessica Alves]

I read once a simple but meaningful piece of writing advice on Stephen King's memoir “On Writing”: read more to write better.

[Michael Tharrington]

That's such great advice!

On a related note, I find that listening to music helps me to play better music. And of course, there's a difference between listening for pleasure and listening with intention... both help, but I think listening with intention gets me there faster!

I think the same is likely true with reading. We can read for pleasure and it'll help us to write better. But we can also read super intently to try and pick up on what folks are doing with their craft and I think that can really help to boost our learning curve!

[Michael Tharrington]

But thats run counter to my core personality trait as a procrastinator, haha!

In all seriousness though, you're absolutely right. You won't get anywhere with your writing if you don't write!

[Michael Tharrington]

That's an awesome way to word it and quite inspiring!

[Erin Bensinger]

A college poetry professor of mine, Diane Seuss, always said "there's no such thing as writer's block, you're just not reading enough."