14 ms·

On Technical Writing

118 points by ming13 7y ago

JeanMarcS 7y ago
« Kids certainly don’t give a damn about them either. » Well I guess it depends on how you educate them. While I’m here eating my (late) breakfast, both are in their room reading. They are 9yo (10 next spring). My son is finishing season 2 of Erin Hunter’s warriors (he loves cat) and my daughter finally catch up on Harry Potter and is reading no2 (they are not allowed to see the movies until they read the book)
- rlayton2 7y ago
  Agreed, what a weird statement by the article's author. My kids love reading books. They don't read on screens much, it has to be a book.
  - coldtea 7y ago
    >what a weird statement by the article's author I can never understand this reasoning. The statement by the article's author covers 80% or more of kids, who mostly don't read (and 90% or more reads zero to one book a year). It's like someone noting that "people have one nose" and somebody arguing, "This is such a weird statement to make, my neighbour, who was on a traffic accident, has none"! Extreme Outliers (1-2%), or even smaller minorities (3-10%) don't make a general statement "weird", at worse they make it not exhaustive. (...) Conducted by psychologist and professor Jean Twenge, the study finds that the reading decline among American teens is worse than expected. In 2016, only 16 percent of high school seniors reported daily reading of a book or magazine. Roughly 40 years ago, 60 percent of high school seniors did the same. (...) About a third of 12th graders also said they had not read a book or e-book for pleasure in the last year — which is about triple the number who said so in the 1970s. Not much better for adults: (...) The share of men reading for pleasure on any given day fell from 25 percent in 2004 to 15 percent in 2017, a drop of nearly 40 percent. The decline among women was a more modest 29 percent, from 31 percent in 2003 to 22 percent in 2017. The survey data shows declines in leisure reading across all age levels. (...) Between 2003 and 2016, the amount of time that the average American devoted to reading for personal interest on a daily basis dropped from 0.36 hours to 0.29 hours. (...) From a breakdown of reading by income quartile, it turns out that the rich read more—but they read less and less every year. Americans in the lowest income quartile did manage to read more in 2016 than they did in 2003—a rare trend—but that’s probably a dead-cat bounce; the 2003 number was so low that it was as likely to improve as not. https://www.humanitiesindicators.org/content/indicatordoc.aspx?i=11098 https://www.humanitiesindicators.org/content/indicatordoc.as... Sources: New Yorker, WP, U.S. Department of Labor, Bureau of Labor Statistics, etc.
    - minblaster 7y ago
      Yep, many think their single n=1 counterexample dismantles the truth of a general trend. Especially when they fail to realize the selection bias of their commenting on a forum for curiosity-driven technology enthusiasts.
      - JeanMarcS 7y ago
        Why do you assume that American kids decline to read is a reflection of a world trend ? I’m sorry but those numbers are not true everywhere. For example, in France, a study from 2016 shows that 78% of kids read for pleasure, with an average of 6 books per trimester. That’s not that bad I guess, but hey, what do I know, I am not American... So sorry but no, my example is not an n=1. But more a n= 78% of around 70M persons country.
        coldtea 7y ago
        >Why do you assume that American kids decline to read is a reflection of a world trend ? Well what happens in the US, more often than not, is usually translated into a global trend too (and surely a western trend), even if it takes a decade or so (anything from fast-food to hip-hop to social trends, etc.). It's not like the US situation for that matter is unique in some way. Kids now have video games, unlimited TV options (even up to the 90s TV options were restricted), YouTube, social media, and several other things besides. Reading books is very low in their priorities. >For example, in France, a study from 2016 shows that 78% of kids read for pleasure, with an average of 6 books per trimester. From that number alone, and with empirical observations as a fellow European, I'm curious study and its methodology. Maybe done to promote the "good work" done by the culture or education ministry, or to make the book industry look good (to investors) or trendy (to kids)? Care to post the link to the study? Does it include comic books in that "reading"? Meanwhile, how about this? https://www.thelocal.fr/20171205/french-school-children-ranked-worst-at-reading-in-europe https://www.thelocal.fr/20171205/french-school-children-rank...
- aspaceman 7y ago
  "Kids these days" never really goes away huh? Funny how smart phones and social media will be our version of that.
  - jpxw 7y ago
    “The children now love luxury; they have bad manners, contempt for authority; they show disrespect for elders and love chatter in place of exercise. Children are now tyrants, not the servants of their households. They no longer rise when elders enter the room. They contradict their parents, chatter before company, gobble up dainties at the table, cross their legs, and tyrannize their teachers.” ~ Socrates
    - BossingAround 7y ago
      In case you're wondering why you're being downvoted, the quote seems to be fake [1]. The picture that sometimes go with it, [2], is fake as well. [1] https://quoteinvestigator.com/2010/05/01/misbehave/ https://quoteinvestigator.com/2010/05/01/misbehave/ [2] https://imgur.com/jwSls6X https://imgur.com/jwSls6X
      - jerf 7y ago
        The other stupid thing about that supposed quote is that the presumption that he must have been wrong may not be justified. Socrates is thought to have lived 470-399BC. By the end of that lifetime, it would have been obvious to an impartial observer that Athenian power was fading; another generation or two later and Athens was no longer an independent power. Yeah, it seems like the previous generation is always upset about the next generation, but they're not always wrong. Humanity has survived, sure, but most of the civilizations those sentiments were coming from haven't.
        BossingAround 7y ago
        That's an interesting observation. I wonder whether a falling empire correlates to children misbehaving at schools. I wonder whether studies were done on it in Britain or Spain, both of which you could say had empires which collapsed (though this did not threaten their whole existence).
kristianc 7y ago
> There were no recommendation engines of course so I went through everything, itching to consume experiences left behind by humanity. Sounds like an addiction, right? Well, it kinda was. Well, there kind of were. I doubt you would end up reading The Hobbit, The Three Musketeers and Sherlock Holmes purely by accident. The idea that the best content bubbling to the top of the popular consciousness is merely a product of modern ML recommendation engines is for the birds.
- soonerroadie 7y ago
  Of course there were recommendation engines - they were called librarians.
baby 7y ago
This article is actually quite empty, it starts like it is going to be about how to write good technical content, then becomes an auto-biography, then becomes an article on how one can get started blogging, then just end abruptly with some statistics that probably nobody cares. So if you came here to know how to write, Stephen King wrote a book "On Writing" that is quite interesting and mostly reads like a novel. See it as a "I'll read this and I'll get motivated to write". If you came here to understand how to get into blogging: just start. Create a wordpress, and just start writing. Focus on content, not on form. After a while, you can think about a domain name, about a custom theme, or about hosting this yourself on github with hugo. But don't start with the technical parts of managing a blog, just write. If you came here to understand how you can become a good technical writer: keep writing. Consistence over years of writing is what makes you a good writer. The ultimate technique for me is to give an interactive talk to people about your ideas, and see where your audience get stuck, where they ask questions, how different ways of explaining something get the point across. Malcolm Gladwell does more than this: he explains an idea multiple times in different ways. If you have the page count to do this, do it. Different people need different ways of explaining. (shameless plug: I'm writing a book on crypto https://www.manning.com/books/real-world-cryptography?a_aid=Realworldcrypto&a_bid=ad500e09 https://www.manning.com/books/real-world-cryptography?a_aid=...)
- dnh44 7y ago
  William Zinsser’s “On Writing Well” is also quite illuminating in regards to writing non-fiction. https://www.harpercollins.com/9780060891541/on-writing-well/ https://www.harpercollins.com/9780060891541/on-writing-well/
  - arvinsim 7y ago
    I would second this. I always go back to this book once in a while to review how to do non-fiction writing.
  - criddell 7y ago
    Have you read Steven Pinker's Sense of Style? https://stevenpinker.com/publications/sense-style-thinking-persons-guide-writing-21st-century https://stevenpinker.com/publications/sense-style-thinking-p... I was thinking about reading it but it's hard to find reviews of the book that don't include praise or criticism of Pinker's other work or the author himself.
phlakaton 7y ago
> Btw, conferences and events are dead. The author lost me right there.
voidhorse 7y ago
This article, like many on “technical writing” conflates techincal writing and writing about technology. In my estimation, they’re two different things. Technical Writing is a profession with a massive set of practices, relatively well-prescribed goals, and a long history. It’s a discipline that has almost nothing to do with Stephen King and Strunk and White—though of course these sources might be applied. Chances are, if you were to ask an professional technical writer about resources for technical writing, they’d point you to a few text books on technical communication or papers or blog posts from people in the industry. Technical writing also has serious consequences. If a manual for a missile has mistakes, it could cost thousands of dollars or thousands of lives. Stephen King’s advice isn’t quite as helpful in such perilous situations. Writing about technology, I think, is closer to what the author is actually pursuing here—and most tech blogs better fit this classification than technical writing. Writing about technology is more free form, more whimsical, full of opinion, intimations of possible approaches or solutions but not hardened proceedural documentation. It might seem a bit pedantic to make such a distinction, but I would really love it if more people honored it. For instance, this article was a bit of false advertising, since I thought it’d be about technical writing in the professional sense (i.e. writing documentation) and not about writing about technology in a more casual, opinionated way. It’s similar to the distinction between programming and software engineering—they’re quite distinct pusuits, even though the tools and techniques considered overlap.
- kaycebasques 7y ago
  My guiding goal as a practicing technical writer is how do I transfer knowledge as efficiently as possible? For that reason I think it’s a skill that is applicable to anyone whose job depends upon a lot of collaboration, which is why I think we see the topic come up somewhat frequently here on HN. I 100% agree that technical writing is a discipline with a specific meaning and is not the same thing as writing about technology.
- blululu 7y ago
  Agreed. I too would have enjoyed a discussion of the challenges of technical writing. Especially since I feel like it is becoming increasingly common forego hiring technical writers and have engineers write documentation. Which is a shame because a lot of people rely on documentation for their work and inconsistent/low quality documentation really hurts a technical product.
herodotus 7y ago
I am surprised that someone who claims to have been an avid reader writes so poorly. Consider, for example, "Fast-forward to the last year of school. I’ve started writing. It was nothing special really, short fictional stories there and there." The author's tense is muddled, and I have no idea what "there and there" means. Better would be "Fast-forward to my last year of school. I started writing. It was nothing special really, just some short stories." There were a few instances where the author should have used "I" rather than "I've". In fact, I would encourage this author to avoid such contractions altogether. The goal of writing at least one article a month is laudable, but this author should work on writing craft fundamentals. Perhaps a book like The Elements of Style would help. Even better would be a tutor or coach.

118 points by ming13 7y ago

« Kids certainly don’t give a damn about them either. » Well I guess it depends on how you educate them. While I’m here eating my (late) breakfast, both are in their room reading. They are 9yo (10 next spring). My son is finishing season 2 of Erin Hunter’s warriors (he loves cat) and my daughter finally catch up on Harry Potter and is reading no2 (they are not allowed to see the movies until they read the book)

rlayton2 7y ago
Agreed, what a weird statement by the article's author. My kids love reading books. They don't read on screens much, it has to be a book.
- coldtea 7y ago
  >what a weird statement by the article's author I can never understand this reasoning. The statement by the article's author covers 80% or more of kids, who mostly don't read (and 90% or more reads zero to one book a year). It's like someone noting that "people have one nose" and somebody arguing, "This is such a weird statement to make, my neighbour, who was on a traffic accident, has none"! Extreme Outliers (1-2%), or even smaller minorities (3-10%) don't make a general statement "weird", at worse they make it not exhaustive. (...) Conducted by psychologist and professor Jean Twenge, the study finds that the reading decline among American teens is worse than expected. In 2016, only 16 percent of high school seniors reported daily reading of a book or magazine. Roughly 40 years ago, 60 percent of high school seniors did the same. (...) About a third of 12th graders also said they had not read a book or e-book for pleasure in the last year — which is about triple the number who said so in the 1970s. Not much better for adults: (...) The share of men reading for pleasure on any given day fell from 25 percent in 2004 to 15 percent in 2017, a drop of nearly 40 percent. The decline among women was a more modest 29 percent, from 31 percent in 2003 to 22 percent in 2017. The survey data shows declines in leisure reading across all age levels. (...) Between 2003 and 2016, the amount of time that the average American devoted to reading for personal interest on a daily basis dropped from 0.36 hours to 0.29 hours. (...) From a breakdown of reading by income quartile, it turns out that the rich read more—but they read less and less every year. Americans in the lowest income quartile did manage to read more in 2016 than they did in 2003—a rare trend—but that’s probably a dead-cat bounce; the 2003 number was so low that it was as likely to improve as not. https://www.humanitiesindicators.org/content/indicatordoc.aspx?i=11098 https://www.humanitiesindicators.org/content/indicatordoc.as... Sources: New Yorker, WP, U.S. Department of Labor, Bureau of Labor Statistics, etc.
  - minblaster 7y ago
    Yep, many think their single n=1 counterexample dismantles the truth of a general trend. Especially when they fail to realize the selection bias of their commenting on a forum for curiosity-driven technology enthusiasts.
    - JeanMarcS 7y ago
      Why do you assume that American kids decline to read is a reflection of a world trend ? I’m sorry but those numbers are not true everywhere. For example, in France, a study from 2016 shows that 78% of kids read for pleasure, with an average of 6 books per trimester. That’s not that bad I guess, but hey, what do I know, I am not American... So sorry but no, my example is not an n=1. But more a n= 78% of around 70M persons country.
      - coldtea 7y ago
        >Why do you assume that American kids decline to read is a reflection of a world trend ? Well what happens in the US, more often than not, is usually translated into a global trend too (and surely a western trend), even if it takes a decade or so (anything from fast-food to hip-hop to social trends, etc.). It's not like the US situation for that matter is unique in some way. Kids now have video games, unlimited TV options (even up to the 90s TV options were restricted), YouTube, social media, and several other things besides. Reading books is very low in their priorities. >For example, in France, a study from 2016 shows that 78% of kids read for pleasure, with an average of 6 books per trimester. From that number alone, and with empirical observations as a fellow European, I'm curious study and its methodology. Maybe done to promote the "good work" done by the culture or education ministry, or to make the book industry look good (to investors) or trendy (to kids)? Care to post the link to the study? Does it include comic books in that "reading"? Meanwhile, how about this? https://www.thelocal.fr/20171205/french-school-children-ranked-worst-at-reading-in-europe https://www.thelocal.fr/20171205/french-school-children-rank...
aspaceman 7y ago
"Kids these days" never really goes away huh? Funny how smart phones and social media will be our version of that.
- jpxw 7y ago
  “The children now love luxury; they have bad manners, contempt for authority; they show disrespect for elders and love chatter in place of exercise. Children are now tyrants, not the servants of their households. They no longer rise when elders enter the room. They contradict their parents, chatter before company, gobble up dainties at the table, cross their legs, and tyrannize their teachers.” ~ Socrates
  - BossingAround 7y ago
    In case you're wondering why you're being downvoted, the quote seems to be fake [1]. The picture that sometimes go with it, [2], is fake as well. [1] https://quoteinvestigator.com/2010/05/01/misbehave/ https://quoteinvestigator.com/2010/05/01/misbehave/ [2] https://imgur.com/jwSls6X https://imgur.com/jwSls6X
    - jerf 7y ago
      The other stupid thing about that supposed quote is that the presumption that he must have been wrong may not be justified. Socrates is thought to have lived 470-399BC. By the end of that lifetime, it would have been obvious to an impartial observer that Athenian power was fading; another generation or two later and Athens was no longer an independent power. Yeah, it seems like the previous generation is always upset about the next generation, but they're not always wrong. Humanity has survived, sure, but most of the civilizations those sentiments were coming from haven't.
      - BossingAround 7y ago
        That's an interesting observation. I wonder whether a falling empire correlates to children misbehaving at schools. I wonder whether studies were done on it in Britain or Spain, both of which you could say had empires which collapsed (though this did not threaten their whole existence).

kristianc 7y ago

> There were no recommendation engines of course so I went through everything, itching to consume experiences left behind by humanity. Sounds like an addiction, right? Well, it kinda was. Well, there kind of were. I doubt you would end up reading The Hobbit, The Three Musketeers and Sherlock Holmes purely by accident. The idea that the best content bubbling to the top of the popular consciousness is merely a product of modern ML recommendation engines is for the birds.

soonerroadie 7y ago
Of course there were recommendation engines - they were called librarians.

baby 7y ago

This article is actually quite empty, it starts like it is going to be about how to write good technical content, then becomes an auto-biography, then becomes an article on how one can get started blogging, then just end abruptly with some statistics that probably nobody cares. So if you came here to know how to write, Stephen King wrote a book "On Writing" that is quite interesting and mostly reads like a novel. See it as a "I'll read this and I'll get motivated to write". If you came here to understand how to get into blogging: just start. Create a wordpress, and just start writing. Focus on content, not on form. After a while, you can think about a domain name, about a custom theme, or about hosting this yourself on github with hugo. But don't start with the technical parts of managing a blog, just write. If you came here to understand how you can become a good technical writer: keep writing. Consistence over years of writing is what makes you a good writer. The ultimate technique for me is to give an interactive talk to people about your ideas, and see where your audience get stuck, where they ask questions, how different ways of explaining something get the point across. Malcolm Gladwell does more than this: he explains an idea multiple times in different ways. If you have the page count to do this, do it. Different people need different ways of explaining. (shameless plug: I'm writing a book on crypto https://www.manning.com/books/real-world-cryptography?a_aid=Realworldcrypto&a_bid=ad500e09 https://www.manning.com/books/real-world-cryptography?a_aid=...)

dnh44 7y ago
William Zinsser’s “On Writing Well” is also quite illuminating in regards to writing non-fiction. https://www.harpercollins.com/9780060891541/on-writing-well/ https://www.harpercollins.com/9780060891541/on-writing-well/
- arvinsim 7y ago
  I would second this. I always go back to this book once in a while to review how to do non-fiction writing.
- criddell 7y ago
  Have you read Steven Pinker's Sense of Style? https://stevenpinker.com/publications/sense-style-thinking-persons-guide-writing-21st-century https://stevenpinker.com/publications/sense-style-thinking-p... I was thinking about reading it but it's hard to find reviews of the book that don't include praise or criticism of Pinker's other work or the author himself.

phlakaton 7y ago

> Btw, conferences and events are dead. The author lost me right there.

voidhorse 7y ago

This article, like many on “technical writing” conflates techincal writing and writing about technology. In my estimation, they’re two different things. Technical Writing is a profession with a massive set of practices, relatively well-prescribed goals, and a long history. It’s a discipline that has almost nothing to do with Stephen King and Strunk and White—though of course these sources might be applied. Chances are, if you were to ask an professional technical writer about resources for technical writing, they’d point you to a few text books on technical communication or papers or blog posts from people in the industry. Technical writing also has serious consequences. If a manual for a missile has mistakes, it could cost thousands of dollars or thousands of lives. Stephen King’s advice isn’t quite as helpful in such perilous situations. Writing about technology, I think, is closer to what the author is actually pursuing here—and most tech blogs better fit this classification than technical writing. Writing about technology is more free form, more whimsical, full of opinion, intimations of possible approaches or solutions but not hardened proceedural documentation. It might seem a bit pedantic to make such a distinction, but I would really love it if more people honored it. For instance, this article was a bit of false advertising, since I thought it’d be about technical writing in the professional sense (i.e. writing documentation) and not about writing about technology in a more casual, opinionated way. It’s similar to the distinction between programming and software engineering—they’re quite distinct pusuits, even though the tools and techniques considered overlap.

kaycebasques 7y ago
My guiding goal as a practicing technical writer is how do I transfer knowledge as efficiently as possible? For that reason I think it’s a skill that is applicable to anyone whose job depends upon a lot of collaboration, which is why I think we see the topic come up somewhat frequently here on HN. I 100% agree that technical writing is a discipline with a specific meaning and is not the same thing as writing about technology.
blululu 7y ago
Agreed. I too would have enjoyed a discussion of the challenges of technical writing. Especially since I feel like it is becoming increasingly common forego hiring technical writers and have engineers write documentation. Which is a shame because a lot of people rely on documentation for their work and inconsistent/low quality documentation really hurts a technical product.

herodotus 7y ago

I am surprised that someone who claims to have been an avid reader writes so poorly. Consider, for example, "Fast-forward to the last year of school. I’ve started writing. It was nothing special really, short fictional stories there and there." The author's tense is muddled, and I have no idea what "there and there" means. Better would be "Fast-forward to my last year of school. I started writing. It was nothing special really, just some short stories." There were a few instances where the author should have used "I" rather than "I've". In fact, I would encourage this author to avoid such contractions altogether. The goal of writing at least one article a month is laudable, but this author should work on writing craft fundamentals. Perhaps a book like The Elements of Style would help. Even better would be a tutor or coach.