6 ms·
On Writing Well
- ruuda 2y agohttps://developers.google.com/tech-writing https://developers.google.com/tech-writing covers the same topics in more detail.
- surfingdino 2y agoAlso, get a copy of Strunk & White's "The Elements of Style" and read it often.
- mo_42 2y agoFor 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 2y ago“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 2y agoYeah, it's surprisingly poorly written for an article about writing well :-/
- eatonphil 2y agoOn 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 2y agoWanna say me and my friend keep loosing this wonderful book.
- hubraumhugo 2y agoAs 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 2y agoThe post is not about the book. In fact, as he commented here, he had never heard of the book.
- paulpauper 2y agoThen 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 2y agoAgreed. 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 2y agoThere 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 2y agoThis one? https://evaparish.com/blog/how-i-edit https://evaparish.com/blog/how-i-edit
- altgans 2y agoI think so, yes, 80% confident. Awesome, thank you!
- kuba_dmp 2y agoReading 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-bullshit https://www.goodreads.com/book/show/28448362-writing-without...
- chrisweekly 2y agoRelated 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 2y agoI hope I’m not the only one who cringes at the “asks” terminology, in the context of “writing well”.
- mihaic 2y agoYeah, ironically in a post on writing well, the author turns a verb into a noun and then uses it to mean both "questions" and "requests".
- deleted 2y ago[deleted]
- stavros 2y agoI'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?"
- KineticLensman 2y agoYes, '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 2y agoAnother 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.”
- BossingAround 2y agoSome 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, ..."
- deleted 2y ago[deleted]
- deleted 2y ago[deleted]
- deleted 2y ago[deleted]
- condortg 2y agoFor anyone interested in the topic, I would recommend reading this article: https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing https://www.americanscientist.org/blog/the-long-view/the-sci...
- rramadass 2y agoFor Technical Writing, follow "The Minto Pyramid Principle" (https://untools.co/minto-pyramid/ https://untools.co/minto-pyramid/), keep everything Concise, Precise, use Assertive/Definitive voice and show Usage with Examples in the beginning itself.
- derstander 2y agoJust 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.
- gewaltig 2y agoI thought the same. Zinsser’s classic changed the way I perceived writing.
- d_bud 2y agoZinsser’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.
- zodvik 2y agoAuthor here. TIL about the book. For reference https://www.goodreads.com/book/show/53343.On_Writing_Well https://www.goodreads.com/book/show/53343.On_Writing_Well