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

Software engineers should write

shubhro.com

Post reply on HN
Print view View original

121–130 of 166 posts

Re: Software engineers should write

#121

Post by bbcbasic »

slavik81 wrote: post #103
bbcbasic wrote: post #102

Earlier quoted context omitted.

I agree. Funny how people worry about documentation going out of date, but not code going out of date. I guess it is more acceptable to have a bug in the code than a mistake in the documentation.

Exactly the opposite. The documentation gets out of date because people update the code without updating the documentation.

Yes that is a problem. However the question is what do you prefer, no documentation, or documentation that may be out of date? As a detective (which let's face it that is what an Enterprise programmer's job is to an extent) it is nice to have some information which you can scrutinize, rather than nothing.

Re: Software engineers should write

#122

Post by mastazi »

As a former English-kid (well I grew up in Italy so I was an "Italian-kid"), who became a programmer after having worked as a journalist, I completely agree with the article. Although code can be seen merely as a series of mathematical statements, nonetheless it has its 'grammar', syntax and semantics, just like any natural language does. I have noticed that in Australia (where I got my bachelor in IT) you are required to write essays on a regular basis even if you are studying scientific subjects and I think that's good.

Re: Software engineers should write

#124

Post by tjradcliffe »

platz wrote: post #111
tjradcliffe wrote: post #70

Earlier quoted context omitted.

He was right. In terms of sustained effort and difficulty, writing a novel is comparable to getting a PhD or creating and shipping a major embedded application from the bare metal on up. Maybe be more difficult. Getting a PhD requires considerable persistence and a modicum of intelligence, but there are supporting and sustaining systems that make it easier. You have an advisor and a committee who in the best of all p…

Some of my friends have written some fiction novels. I wish they'd started out with short stories before going for the novel.

It might have helped... or not. Although there are lots of things you can learn from short stories, they are not all that similar to short stories in terms of the skills an author needs.

For a short story writer the primary challenge is to introduce your characters, their problem and their actions in as few words as possible. Short fiction is focused. You've got one or two main characters who have one problem.

Novels sprawl. They have many characters, many problems, and are typically spread over a much large time-scale. There are novels that aren't much more than "longer short stories" but they tend to be pretty thin stuff.

So for a short story writer the problem is cutting out anything that is not absolutely necessary to the finished whole. For a novelist the problem is keeping in control of the huge unwieldy structure, because it's just really difficult to hold it all in your head at once.

Software analogy: micro-controller development vs desktop application development. For the first you're mostly worried about resource usage. For the second you're mostly worried about it turning into an e-mail client, operating system, or EMACS over the course of development.

I had written and published a very small number of short stories before writing a novel, but didn't really study them until after. One of the great things about short stories, it turns out, is that there's so little money in them that there are classes taught by really good authors very cheaply, at least in Canada (for anyone in Vancouver I highly recommend Caroline Adderson's weirdly-named but absolutely excellent course "Fiction Series for the Weekend Student" from SFU, which fundamentally focuses on short story structure: http://www.sfu.ca/continuing-studies/courses/cpw/fiction-ser...)

I did write a couple of throw-away novels before writing "Darwin's Theorem", and while that process was useful, it didn't really prepare me for the real thing, which involves far more re-writing than anything else (at least the way I do it.) A book you're writing for practice can have all kinds of flaws... a book you're writing to publish has to be as perfect as you can make it (think of it as the difference between a weekend project for your own amusement vs code you're going to ship.)

Re: Software engineers should write

#125

Post by georgemcbay »

edpichler wrote: post #55
sophacles wrote: post #53

Earlier quoted context omitted.

Tangential - Just want to give you some feedback on your comment, since you are wanting to improve your second language: First: you've overcome a big hurdle in learning a second language, I understood what you are trying to communicate, and I did so on my first reading of it. To me, this means you're already good at english! (By comparison if I tried in my second language, which is German, I would need a few drafts a…

Oh, I really appreciate your corrections, thank you! I understand that reading bad English is really annoying for natives. I try to be careful here on HN, but sometimes I do some mistakes.

I think non-native English speakers think we are more annoyed by it than we actually are.

Any native English speaker who goes online has to be used to English being used very poorly by now, and it is much less annoying when the person making mistakes is a non-native speaker trying to learn rather than a native speaker who is lazy or functionally illiterate.

Everything you've written is completely understandable and most of it is arguably grammatically okay though sometimes phrased in ways that sound unnatural in colloquial English. For example "sometimes I do some mistakes" would be better said "sometimes I make mistakes", though the way you phrased it is perfectly understandable.

Re: Software engineers should write

#126

Post by azeirah »

ivansavz wrote: post #60
kalid wrote: post #24

I've always been a fan of Einstein's quote "If you can't explain it simply, you don't understand it well enough." Writing about a topic is a good test of whether you can explain it simply.

In "physics land" Richard Feynman is famous for his explanatory power, e.g. We tried to take advantage of Richard's talent for clarity by getting him to critique the technical presentations that we made in our product introductions. Before the commercial announcement of the Connection Machine CM-1 and all of our future products, Richard would give a sentence-by-sentence critique of the planned presentation. "Don't sa…

That's an absolutely excellent story. I can recommend it to anyone on this site.

Re: Software engineers should write

#127

Post by stevebmark »

Writing a blog post about technology, such as teaching a library or programming language, or how to accomplish something, or even docs for your own library is really hard to get right. In the programming field I work in, I'd guess about 90% of all tutorials / tech blog posts are poorly written. Even Github READMEs are a minefield of very poorly presented ideas. I would not encourage people to continue to add to this noisy spectrum unless they are already capable of conveying ideas clearly and simply. Most technical articles, including many that front page HN, do not come close to this criteria.

I agree that writing can be helpful for many things, such as expressing emotion, or telling stories, or just a journal. In those scenarios, it's not dangerous to get it wrong. No one will lose their way in a technical project because you can't write cleanly about your dog.

Write anything except technical articles, until someone comments with something like "this was really well written!" Then you can consider adding to the painful cloud of tech articles.

If you release a tech blog post without editing (and largely re-writing) it a minimum of three times, stop doing it. Seriously. You're not helping.

Also, if you're a newcomer to a tech field and get discouraged by trying to learn about something from online resources, 90% of the time it's not you. It's the author being unable to clearly present ideas. Don't get discouraged!

Re: Software engineers should write

#128

Post by mattlutze »

edpichler wrote: post #55
sophacles wrote: post #53

Earlier quoted context omitted.

Tangential - Just want to give you some feedback on your comment, since you are wanting to improve your second language: First: you've overcome a big hurdle in learning a second language, I understood what you are trying to communicate, and I did so on my first reading of it. To me, this means you're already good at english! (By comparison if I tried in my second language, which is German, I would need a few drafts a…

Oh, I really appreciate your corrections, thank you! I understand that reading bad English is really annoying for natives. I try to be careful here on HN, but sometimes I do some mistakes.

For a counter-point, I'm slightly proud of how our (English) language is able to flexibly accommodate a vast array of other-language grammars, while still maintaining understanding and clarity.

The two points that the previous poster highlighted: while perhaps the native-fluent speaker will notice that the phrases have a non-standard form, both sentences are completely intelligible.

Living abroad from the United States has only served to stretch my conception of "proper English" even further.

Re: Software engineers should write

#129

Post by rimantas »

VLM wrote: post #52

Interesting discussion point, Larry Wall, linguist, invented a programming language that is not exactly considered stylish at this time. Implications?

Being linguist does not make you a good writer, just as being theologician does not make you a saint.

Re: Software engineers should write

#130

Post by singingfish »

"Writing is easy: All you do is sit staring at a blank sheet of paper until drops of blood form on your forehead.”

(yeah I've written one book with a readership of thousands, 5/8ths of a phd with a readership of 5 and a bunch of academic articles with a variable readership)

Post reply on HN