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

Ask HN: What are good writing tips for software developers?

news.ycombinator.com

Post reply on HN
Print view View original

61–70 of 70 posts

Re: Ask HN: What are good writing tips for software developers?

#61

Post by ivansavz »

If you're writing a long text (over 2 pages), you should invest the time to proofread it properly, and maybe get it read by a friend or colleague. When the ideas in a text are not clear and logically structured, it can be perceived as disrespect to the readers.

One thing that really helps me to catch typos in my own writing, is the text-to-speech utility built into Mac OS X. It makes it really easy to "hear" typos. Here is a doc with screenshots that explain how to set up a keyboard shortcut for this: https://docs.google.com/document/d/1mApa60zJA8rgEm6T6GF0yIem...

Re: Ask HN: What are good writing tips for software developers?

#62

Post by tmaly »

soneca wrote: post #21
tmaly wrote: post #19

Earlier quoted context omitted.

Thanks, how often would you send out an email for this newsletter?

My plan is to send it weekly, but with shorter texts than this first one. The idea is to be more specific, like: "Tips for a good Pull Request description", "Tips for a good feature deploy announcement email", "Tips for a good user story". What do you think? Any topic you are particularly interested?

It is a bit longer, but how about a series where you outline writing a good README.md for a github project. This would include the descriptions, examples etc. Many times I will come across a project on github that seems interesting, but there is only a single sentence in the README.md

Re: Ask HN: What are good writing tips for software developers?

#63

Post by vram22 »

DannyB2 wrote: post #26

A preposition is a very bad word to end a sentence with. But only a fool would begin or end a sentence with the word but. And only a total idiot would begin or end a sentence with the word and. Anyway, you should never use the word 'anyway'. Even worser to use 'anyways'. And never utilize the word 'utilize' when you could utilize the word 'use' instead. Your doing it wrong if you're sentences confuse the words your a…

There there, never mix up their and there.

Don't write lead when you mean led. (I see this a lot in exec and other bios on company sites.)

Re: Ask HN: What are good writing tips for software developers?

#64

Post by vram22 »

DannyB2 wrote: post #26

A preposition is a very bad word to end a sentence with. But only a fool would begin or end a sentence with the word but. And only a total idiot would begin or end a sentence with the word and. Anyway, you should never use the word 'anyway'. Even worser to use 'anyways'. And never utilize the word 'utilize' when you could utilize the word 'use' instead. Your doing it wrong if you're sentences confuse the words your a…

He he, good ones.

Here's a small Python tool I wrote to help with stuff like this - it can easily be customized to add more suggestions of your own, from this thread or elsewhere:

Cut the crap! An absolutely essential tool for writers:

https://jugad2.blogspot.in/2015/07/cut-crap-absolutely-essen...

Re: Ask HN: What are good writing tips for software developers?

#65

Post by DannyB2 »

anotherevan wrote: post #55
DannyB2 wrote: post #54

Earlier quoted context omitted.

and capitalization

Capitalisation is very important, if for no other reason then it means the difference between helping your Uncle Jack off a horse...

A comma could also be an invaluable tool in that situation. Properly used. And Walmart has them on sale in one dozen packs.

Re: Ask HN: What are good writing tips for software developers?

#66

Post by vram22 »

ivansavz wrote: post #60
DannyB2 wrote: post #26

A preposition is a very bad word to end a sentence with. But only a fool would begin or end a sentence with the word but. And only a total idiot would begin or end a sentence with the word and. Anyway, you should never use the word 'anyway'. Even worser to use 'anyways'. And never utilize the word 'utilize' when you could utilize the word 'use' instead. Your doing it wrong if you're sentences confuse the words your a…

Yes. Definitely agree about use of "utilize." It is a total tell in any piece of writing that is trying to sound "fancy" for nothing. The person who wrote the text loses one star of my respect rating immediately at the first occurrence of "utilize." It's even worse when spoken!

"At this point in time" is another one, can be replaced with just "right now" or even "now". Had to tell a team member of mine that once.

Re: Ask HN: What are good writing tips for software developers?

#68

Post by vram22 »

StriverGuy wrote: post #3

I recommend getting three books and to begin writing at least 500 words per day distraction free (technical, fiction, stream of conscious): 1) On Writing Well - William Zinser https://www.amazon.com/Writing-Well-30th-Anniversary-Nonfict... 2) On Writing - Stephen King- https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft... 3) The Elements of Style - Strunk & White - https://www.amazon.com/Elements-Style-Four…

> and commit messages

I noticed a while ago a trend for commit messages to be in the active voice and present tense. Seems to make them more concise and read better / clearer. Started doing that myself on my projects.

Re: Ask HN: What are good writing tips for software developers?

#69

Post by V-2 »

ambivalents wrote: post #18
V-2 wrote: post #6

Earlier quoted context omitted.

> read good writing That's sort of a Catch-22 right there. Can you tell if "your favorite SF novel" represents good writing without having a grasp on what constitutes good writing to begin with? Is writing like cooking (where you don't really need to cook well yourself to be able to tell)?

By virtue of it being your favorite, I would think it's doing something right. But glibness aside, you could think about as you read: Is it fully engaging you? Is it communicating a complex idea in a simple and/or novel way? Is it making you feel something? Does it make you want to do something? These are all good markers, because writing is really just about communicating ideas well. And if you don't trust your own…

> By virtue of it being your favorite, I would think it's doing something right

That something doesn't have to be the quality of writing as such - eg. I can enjoy a somewhat sloppily written book if the idea behind the plot is captivating and compelling

Re: Ask HN: What are good writing tips for software developers?

#70

Post by DannyB2 »

vram22 wrote: post #63
DannyB2 wrote: post #26

A preposition is a very bad word to end a sentence with. But only a fool would begin or end a sentence with the word but. And only a total idiot would begin or end a sentence with the word and. Anyway, you should never use the word 'anyway'. Even worser to use 'anyways'. And never utilize the word 'utilize' when you could utilize the word 'use' instead. Your doing it wrong if you're sentences confuse the words your a…

There there, never mix up their and there. Don't write lead when you mean led. (I see this a lot in exec and other bios on company sites.)

Don't write loose when you mean lose.
Post reply on HN