Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What I think about when I edit (2019)

evaparish.com

Post reply on HN
Print view View original

111–120 of 138 posts

Re: What I think about when I edit (2019)

#111

Post by Karellen »

> Who are you writing for?

This is the hardest part of writing for me, especially blog posts.

I can never decide if I'm writing for a) highly technical readers who know 95% of the concepts my idea is based on, and I just want to connect the concepts together in a way the they might not have thought of, b) generally technical readers who have a grasp of the concepts my idea is based on, but will need some details to tie them into the idea I'm building on top, or c) readers who are not-especially-technical in the field, who might be nevertheless be interested in how a few things works, and my idea too.

I feel like part of it is that I am all these readers, depending on the subject. I enjoy reading articles about the areas of software dev I'm deeply interested in, but also about the odd idiosyncrasies of software that is used in fields I don't normally cover, but I also enjoy reading articles about e.g. the challenges involved in developing geothermal drilling systems, or elevator systems in 80+ story buildings, despite having very little experience in either.

I keep going through cycles of "If I just explain this part in a bit more detail, the post will be accessible to an order of magnitude more readers" to "this is way too long, I should cut some explanations, or add footnotes, or more wikipedia links" to "I'm assuming way too much previous knowledge here, or asking the reader to do too much extra work to follow my point".

Re: What I think about when I edit (2019)

#112

Post by VladTheImpalor »

Karellen wrote: post #111

> Who are you writing for? This is the hardest part of writing for me, especially blog posts. I can never decide if I'm writing for a) highly technical readers who know 95% of the concepts my idea is based on, and I just want to connect the concepts together in a way the they might not have thought of, b) generally technical readers who have a grasp of the concepts my idea is based on, but will need some details to t…

Good question, and one I'd like to see discussed more too. From my point of you, your point "a)" is the one I never choose. In my opinion, one could rarely write something for that audience which might be novel to them. Perhaps I'm just not that smart, but to me, when I picture the true masters in my field, I rarely need to communicate anything to them that they haven't figured out for themselves already, and in the rare case that I might, those types of people don't mind a bit of revisiting of the fundamentals anyway.

My favourite type of writing is one that also comes in handy to myself a couple of years down the line, which inevitably involves a modicum of handholding and starting from some fundamentals. So I'd say most of the articles should be b) or c).

Re: What I think about when I edit (2019)

#113

Post by kens »

Karellen wrote: post #111

> Who are you writing for? This is the hardest part of writing for me, especially blog posts. I can never decide if I'm writing for a) highly technical readers who know 95% of the concepts my idea is based on, and I just want to connect the concepts together in a way the they might not have thought of, b) generally technical readers who have a grasp of the concepts my idea is based on, but will need some details to t…

Yeah, I find picking the audience difficult too. For my blog posts, I want to include the details for specialized readers, but also make the post accessible to the generally technical readers (roughly the HN crowd). (If I wanted to write for only the first group, I'd write academic papers.)

My solutions are to add enough background for someone who isn't an expert (even if it seems repetitive), and to use extensive footnotes for information that most people won't care about. Also, I try to put topics into a broader framework: a few paragraphs on history and why the topic is important. A narrative framework helps too, so even if someone doesn't follow all the details, they get a sense of going on a path e.g. from problem to solution. I also try to break up massive chunks of text with photos or diagrams but worry that I lean on this too heavily.

When I read popular books on scientific topics, I try to study the techniques that they use. For example, "An immense world" is crammed full of interesting facts and stories, keeping the book even though it is discussing technical concepts of sensory perception. "Immune" describes the immune system in detail, making heavy use of metaphors and imagery and repeating these throughout the book. Other books focus on the people, moving the technical details into the background.

I'm no expert on this, of course. People seem to like my blog posts, though, so I figured I'd share my thoughts.

Re: What I think about when I edit (2019)

#114

Post by stavros »

korymath wrote: post #110
avg_dev wrote: post #104

Earlier quoted context omitted.

I really got a lot out of the article. I think it will help my write more succinctly and clearly and to be better understood. One question: after writing the sentence “I really got a lot out of the article.”, I wondered: is this extraneous? Is this clear? Am I saying precisely what I mean? And I think, yes, I meant exactly what I said, and I went into detail in the following sentence. I am just curious what you think…

I am not the author, and am sharing feedback because you asked with honest curiosity. Your writing is not clear to me. Using the word “really” is extraneous. Using “I think” is also extraneous; I assumed these are your thoughts. As the author notes, replace “it” with “the article”, or better yet a specific quote or idea distilled from the article. Helped “my write” should be helped “me write”. You use two -ly adverbs…

I really (err, vehemently) disagree with this feedback.

> Your writing is not clear to me. Using the word “really” is extraneous.

What's not clear? He said the article helped him, it seems pretty clear to me. The "really" was for emphasis, which is fine.

> Using “I think” is also extraneous; I assumed these are your thoughts.

"I think" indicates the degree of certainty. The author is uncertain but deems it likely.

> As the author notes, replace “it” with “the article”, or better yet a specific quote or idea distilled from the article.

The previous sentence says "the article", and the next one says "it" to avoid repetition. Saying "the article" twice would be awkward.

Very odd feedback, given how obviously out of place the corrected sentence would look.

Re: What I think about when I edit (2019)

#115

Post by hansvm »

gghh wrote: post #79
hansvm wrote: post #75

Earlier quoted context omitted.

> monads, "just" I think that line is usually quoting a popular joke from a comedic tour of various programming languages, and "just" is appropriate. > A monad is just a monoid in the category of endofunctors. What's the problem?

I see. It was the first sentence that came to mind. The point I'm trying to make is, in my experience, "just" is often abused, as it conveniently relieves one from providing a sound argument.

Totally agreed. Your other examples were spot-on, and the general sentiment also makes sense to me.

Re: What I think about when I edit (2019)

#116

Post by svat »

kd5bjo wrote: post #76
medstrom wrote: post #30

Earlier quoted context omitted.

"They merged the pull request" sounds fine to me.

In context, though, the passive version can sometimes make for smoother reading. My general rule of thumb is that each sentence should establish context at the beginning by referring to the preceding material and then introduce its new idea at the end— Whether it’s best to start with the maintainer or the pull request depends on which of those you’ve already been discussing. (I didn’t come up with this idea, but I un…

Possibly from here?

* The Science of Scientific Writing (1990) by George Gopen and Judith Swan: https://web.archive.org/web/20240120063715/https://www.ameri...

They say:

> In our experience, the misplacement of old and new information turns out to be the No. 1 problem in American professional writing today. […] Put in the topic position [the beginning of the sentence] the old information that links backward; put in the stress position [the end of the sentence] the new information you want the reader to emphasize.

It's a useful article, that I also mentioned in this answer: https://academia.stackexchange.com/questions/85286/why-do-re... — see also this video https://www.youtube.com/watch?v=jLPCdDp_LE0 of Judy Swan, one of the co-authors (the accompanying handout is https://web.archive.org/web/20170331212200/https://www.cmu.e...).

Re: What I think about when I edit (2019)

#117

Post by chungmin »

gghh wrote: post #74

If I could add one prescription to TFA, it would be to avoid using "just" (the adverb, as in "simply") at all costs. "A monad is just a monoid in the category of endofunctors." Maybe it is, maybe it isn't, but none of that is simple. There's that math joke about proof methods, and this would be "proof by intimidation". When describing a process: "To measure the inverse reactive current in unilateral phase detractors,…

What is TFA?

Re: What I think about when I edit (2019)

#118

Post by quaddo »

Back around 20 years ago I was with an MSP. We depended heavily on having a well written - as current as possible - prod guide for all operations.

At some point it occurred to me that there was likely a way to draw upon the experiences of those who came before us. In my case, it seemed fitting to use newspapers as a reference.

Somewhere I’d come across a concise guideline, a list of do’s and don’ts. The only thing I clearly recall now is keeping the key info “above the fold”, which is likely something that might puzzle someone who has never handled a newspaper. Even so, the concept is easy to share and grasp.

I wish I’d kept that list. I’ve tried looking for it within the past couple years, to no avail.

Re: What I think about when I edit (2019)

#119

Post by ARandomerDude »

> Don’t use adverbs

> There is nothing inherently wrong with adverbs. They are just part of a category of things that I believe are lazy in writing.

Comparing this quote to the rest of the article, it appears the italics convey vocal emphasis. I find it somewhat ironic that “inherently” is an adverb.

Post reply on HN