[HN Gopher] On Writing Well
___________________________________________________________________
On Writing Well
Author : free
Score : 125 points
Date : 2024-08-20 10:54 UTC (4 days ago)
(HTM) web link (zodvik.com)
(TXT) w3m dump (zodvik.com)
| stavros wrote:
| I'd add "don't use demonstratives, like 'this' and 'that', repeat
| the clause". Sometimes, "that" is ambiguous, leading to unclear
| writing.
|
| E.g. "The foo program is running on the bar server. Who is in
| charge of that?" vs "The foo program is running on the bar
| server. Who is in charge of the bar server?"
| BossingAround wrote:
| Some times, the writers don't want to repeat themselves because
| they were taught that it's "poor writing." And I'd agree,
| maybe, in (some) prose.
|
| But in tech docs, please, repeat yourself instead of using
| "this", "that", "those", etc., even when perfectly non-
| ambiguous.
|
| This should be preferred "The service is now ready. To check
| the service's status, ..." over this "The service is now ready.
| To check its status, ..."
| esquivalience wrote:
| I found your last paragraph entirely unambiguous at all three
| levels, which led me to disgree with your overall point.
| Before that I was with you!
| karmakaze wrote:
| Many 'rules' including this one can be broken if you know
| the tradeoffs and can make the case-by-case choices
| correctly. But that was a poor example for motivating a
| behaviour.
| langcss wrote:
| The benefit of "The service is now ready. To check the
| service's status, ..."
|
| Is when someone needs to amend this sentence later, e.g.
| inserting another point:
|
| "The service is now ready. This means you can query the
| health endpoint. To check the service's status, ..."
|
| It makes the writing less likely to become ambiguous.
|
| Most documents I see in work will constantly have sentences
| added/removed as things change.
| andirk wrote:
| We should write with *pointers.
| KineticLensman wrote:
| > the writers don't want to repeat themselves because they
| were taught that it's "poor writing."
|
| Yes! As you say, it massively depends on whether you are
| writing fiction or non-fiction. In any sort of formal
| document, especially technical reports, etc, the reader
| should _never_ have to spend time working out what the author
| means. I used to be a doc reviewer in a previous life, and
| lost count of the number of times docs used different terms
| to mean the same thing, especially where multiple authors
| were involved, or a single author was writing different
| sections at different times.
|
| General plea: If you value your readers, please, please get
| someone else to check a doc to look for these sorts of
| problems. If multiple authors are involved, always get
| someone on the team (a lead author?) to do this check even
| before submitting it for formal review.
| latexr wrote:
| Repeating the clause can be useful, but I don't think it should
| be used as a general rule. Avoiding ambiguity does not mean
| forcing repetition and making dull prose. Example:
|
| > The foo program is running on the bar server. Who is in
| charge of the latter?
|
| Though in general that1 is still weak. Depending on the
| surrounding context (which isn't present in your comment) and
| the main idea, a possibly better example:
|
| > Who is in charge of the bar server running the foo program?
|
| Without a real use case, we could spend days discussing what is
| "better".
|
| Though yes, removing "that" can improve the text, thought that2
| doesn't mean you need to replace it with anything. Let's take
| the first paragraph in the article:
|
| > Writing a technical document is surprisingly hard. That is
| not because of the skill to tell a story. It's because writing
| forces a level of clarity that is easy to gloss over while
| thinking through a topic.
|
| An alternative without any "that":
|
| > Writing a technical document is surprisingly hard. Not
| because of the skill required to tell a story, but because
| writing forces a level of clarity otherwise easy to gloss over
| while thinking through a topic.
|
| 1 I don't think there's any ambiguity the "that" is referring
| to the previous sentence.
|
| 2 I don't think there's any ambiguity the "that" is referring
| to improving the text.
| nvader wrote:
| I want you to know that1 I enjoyed reading this comment, more
| than just an upvote could convey.
|
| 1 ;)
| KineticLensman wrote:
| Yes, 'this' can be really problematic.
|
| There are two problems with using 'this': Firstly, there may be
| ambiguity in what 'this' refers to. If a paragraph starts with
| 'this means...' or similar, it is impossible to understand the
| paragraph without looking back through the text - which of
| course makes it hard to dip into a text (e.g. especially in
| non-fiction, where readers may dip in to find some specific
| fact). Furthermore, any unit of text starting with 'this'
| cannot be copied and pasted somewhere else (e.g. from the main
| body of a report into the conclusions), where the meaning of
| 'this' is completely lost.
|
| I think the problem sometimes happens because the author is
| writing in a flow state (they are 'in the zone') and is
| creating text that relates to their current mental model of
| something. This mental state is of course not accessible to a
| reader, or perhaps not even to the same author at a later date.
|
| Solutions include getting an independent review by someone who
| isn't also involved in the writing process, or if this is
| impossible, reviewing the text yourself after leaving it alone
| for a while. The 'this at the start of a text unit' problem is
| analogous to a linting check and doesn't need to be done by a
| domain expert.
| neuralRiot wrote:
| Another thing worth pointing out is that technical texts are
| rarely read entirely as a literary piece, so repeating things
| is a welcome thing. As someone who spends great part of the day
| reading datasheets it is specially annoying having to scan
| through the entire piece to see what something means like for
| example acronyms:
|
| "The setting of these bits is only valid if the BCST bit in
| FBCSTAT is 1, while the FRDY bit in FSTATR is 1."
| condortg wrote:
| For anyone interested in the topic, I would recommend reading
| this article:
|
| https://www.americanscientist.org/blog/the-long-view/the-sci...
| rramadass wrote:
| For Technical Writing, follow "The Minto Pyramid Principle"
| (https://untools.co/minto-pyramid/), keep everything Concise,
| Precise, use Assertive/Definitive voice and show Usage with
| Examples in the beginning itself.
| zodvik wrote:
| At Stripe, this was also framed as BLUF - bottom line up front.
| rramadass wrote:
| BLUF is a Military standard; see article linked to under the
| "sources" section of the above link.
| derstander wrote:
| Just going by the title, I thought this was going to be related
| to William Zinsser's book of the same name. It's not, though of
| course many of the topics are shared between the two.
|
| It's been a few years since I've returned to it, but the material
| in Zinsser's book has been useful to me as an engineer that has
| to occasionally write for both fellow engineers and non-technical
| folks. I would recommend Zinsser's book if you like the content
| in the article and wouldn't mind a bit more.
| zodvik wrote:
| Author here. TIL about the book.
|
| For reference
| https://www.goodreads.com/book/show/53343.On_Writing_Well
| gewaltig wrote:
| I thought the same. Zinsser's classic changed the way I
| perceived writing.
| d_bud wrote:
| Zinsser's book is great. I'd also recommend Stephen King's 'On
| Writing: A memoir of the craft'. A shorter, easier read, shares
| a lot of topics.
| ruuda wrote:
| https://developers.google.com/tech-writing covers the same topics
| in more detail.
| surfingdino wrote:
| Also, get a copy of Strunk & White's "The Elements of Style" and
| read it often.
| mo_42 wrote:
| For technical writing, journalism, etc., one can follow the
| simple rule _no adjectives_.
|
| For prose, replace all common adjectives by more specific or
| descriptive one, or even remove them too and describe properties.
| For example: The F-35 passed by my house. When I heard its sound,
| the jet had already disappeared at the horizon. (This describes
| super-sonic speed without an adjective or an overly precise speed
| number.)
|
| Edit: past perfect based on comment
| loloquwowndueo wrote:
| "Had already disappeared" :) if you're going to give writing
| advice, try to give examples without missing verbs.
|
| Same applies to the article - it's riddled with grammar
| mistakes. "Lot of your readers may not have English as their
| first language."
|
| "test platform that let's anyone run"
| ggambetta wrote:
| Yeah, it's surprisingly poorly written for an article about
| writing well :-/
| eatonphil wrote:
| On Writing Well by Zinsser is my favorite book on nonfiction
| writing. 10/10 recommend to folks who'd like to work on their
| writing.
| assimpleaspossi wrote:
| Wanna say me and my friend keep loosing this wonderful book.
| hubraumhugo wrote:
| As an engineer who became a founder, I cannot recommend the book
| enough. Whether you're improving your landing page, writing your
| pitch deck, reaching out to customers, or developing your company
| and product strategy, communicating effectively in writing is a
| very crucial skill.
|
| Invest in improving your writing skills. It will pay dividends in
| every aspect of your business.
| BeetleB wrote:
| The post is not about the book. In fact, as he commented here,
| he had never heard of the book.
| paulpauper wrote:
| Then how does this account for the success or writers who do not
| write simply or use a more advanced structure or verbosity? I
| think writing tips are overrated. They don't work as well as
| assumed or advertised. Simple writing is great if you're writing
| a brochure or instructional guide, but I don't think it's an iron
| clad rule for expository writing or creative writing or blog
| writing. There are too many exceptions. The best writing is that
| in which the message most aligns with the values of the
| recipient.
| rramadass wrote:
| Agreed. The best writing is based on taking into account the
| subject matter and the intended reading audience. The same is
| also the case with oratory skills.
|
| For example; as a fan of detective fiction i just love the
| different language styles of Arthur Conan Doyle, Edgar Allan
| Poe, G.K.Chesterton, Agatha Christie, Dorothy Sayers, Rex Stout
| etc. Each is unique and designed for the character being
| depicted but all are enjoyable.
| altgans wrote:
| There was another article/blog on hackernews some time ago along
| the lines of 'I'm an editor, here is how I edit my friends texts'
| with some really good advice.
|
| Unfortunately I can't find it anymore -- if someone knows which
| post I mean, I'd appreciate sharing it with me again.
| davekilian wrote:
| This one? https://evaparish.com/blog/how-i-edit
| altgans wrote:
| I think so, yes, 80% confident. Awesome, thank you!
| kuba_dmp wrote:
| Reading it reminded me of a book "Writing without bullshit" which
| adds a few more concepts to what op shared.
|
| Frontloading information is my favorite, where instead of
| building to the core conclusion you start with it and then
| expand.
|
| https://www.goodreads.com/book/show/28448362-writing-without...
| chrisweekly wrote:
| Related book recommendation: "First, You Write a Sentence", by
| Joe Moran. Even if you're not aspiring to improve your own
| writing, and you simply love to read, it's really worthwhile.
| layer8 wrote:
| I hope I'm not the only one who cringes at the "asks"
| terminology, in the context of "writing well".
___________________________________________________________________
(page generated 2024-08-24 23:01 UTC)