Live data from Hacker News

Software engineers should write

shubhro.com

71–80 of 166 posts

Re: Software engineers should write

#71
YMMV:

There is little so obscure as undocumented code.

An old software joke goes, "When code is written, only the programmer and God understand it. Six months later, only God.".

As a result, for continued understanding of code, documentation, to explain the code to a human reader, is crucial. In simple terms, to humans, code without documentation is at best a puzzle problem in translation and otherwise next to meaningless. Use of mnemonic identifier names to make the code readable has created a pidgin-like language that is usually unclear and inadequate.

Thus, writing documentation is crucial, for the next time the code needs to be read and understood, for users, etc.

Thus, net, after too many years with code and softwarem=, I claim (big letters in sky writing, please):

The most important problem, and a severe bottleneck, in computing is the need for more and better technical writing.

My suggestion for some of the best models of such technical writing are a classic text in freshman physics, a classic text in freshman calculus, and, at times, a classic text in college abstract algebra (for examples of especially high precision in technical writing). Otherwise I suggest Knuth's The Art of Computer Programming.

First rule of technical writing: A word used with a meaning not clear in an ordinary dictionary is a term, in technical writing, say, a technical term. Then, before a term is used in the writing, it needs a definition, that is, needs to have been motivated, defined precisely (maybe even mathematically), explained, and illustrated with examples. Then whenever in doubt, when using the term, include a link back to the definition. So the first rule of technical writing is never but never use a term without easy access to the definition. Similarly for acronyms.

Biggest bottleneck in computing .... Sorry 'bout that. YMMV.

Re: Software engineers should write

#72

I was always an "English kid", came close to failing my math subjects in middle school and finally in high school, I did fail Algebra I, and had to re-take it the next year. Meanwhile, I was in advanced programming courses and on my way to take an AP Computer Science course in the last semester of my sophomore year. Looking back, that experience taught me about how important modeling is to pedagogy. The fact is, my A…

> Looking back, that experience taught me about how important modeling is to pedagogy. Very good point! This is the strongest "pitch" for why one should learn math: the modelling superpowers one will acquire. Every function f(x) is a type of model (e.g. mx+b, x^2, e^x, ln(x), cos(x), |x|, etc.), and understanding the function f(x) will allow you to model any phenomenon that exhibits f(x)-like behaviour. [note: I'm wo…

"gain modelling superpowers" makes no sense to someone who doesn't already understand what modelling is and how is can be used. It is also a comical idea to try to market a book toward students these days - getting even a high school student to read anything longer than a few sentences in one sitting is a miracle.

Re: Software engineers should write

#74
I don't know about writing essays, but just writing about your ideas to yourself and showing others is a great way to explore said ideas even further. At least that's what I find. That's why I've started a blog too about 8 months ago and try to get something interesting into it at least once a month. I've had some great discussions with people. I don't like to see it as blog either (in the sense that I want everyone to see what I'm writing), but more of a commentary platform to validate and explore my thoughts.

Obligatory link: ecc-comp.blogspot.ca

Re: Software engineers should write

#75

Earlier quoted context omitted.

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.

You're welcome. Personally, I don't understand when people get annoyed by those things. I figure if someone has done me the favor of learning my language to communicate with me, and they've done so well enough that I understand them, why should I nitpick little errors? I only point out things like this to people who state they are actively trying to improve - because they've done me a favor by being able to communica…

That's a good outlook. I can't tell you how much it irks me when someone is annoyed that someone else doesn't speak English well. I always say "at least their English is better than your ".

Invariably, that outlook is expressed by people who happen to only speak one language.

Re: Software engineers should write

#76

"Even if nobody reads your essay, writing it will make an impact on you." After reading a post in HN ( https://news.ycombinator.com/item?id=5614689 ) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese. I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thi…

As someone trying to learn Portuguese, I should probably start writing in Portuguese.

Re: Software engineers should write

#77

Why stop at essays or technical articles? As an engineer, I've always been fascinated by the structure and inner mechanics of stories - what makes them work. As a hobby I've done a lot of reading around this; I've written three feature-length screenplays, and a novel you can find in Amazon[1], using very structure-centric approaches (as a result, my characters tend to be too flat). Take a look at The Snowflake Method…

I've just completed a screen-writing course, and wrote a feature-length screenplay as part of that process, and was struck by how much like technical writing it was. A screenplay is not a story the way a novel or short story is, but rather a technical description of a story that allows the various people involved to do their jobs: http://www.tjradcliffe.com/?p=1666

Screenplay structure is so tight and formal it's almost like poetry, an analogy I found very useful.

My novel (http://www.amazon.com/Darwins-Theorem-TJ-Radcliffe-ebook/dp/...) was developed much more organically.

I'm an experimental physicist, and the process for me was more like setting up an experiment, from early ideas to failed prototypes to little side explorations to a final result with (hopefully) all the loose ends tied neatly away where the reader can't see what went into the making.

I found Stephen King's book on writing to be one of the best for understanding the organic process of creating stories. If you haven't read it, I'd strongly recommend it: http://www.amazon.com/Writing-Stephen-King-ebook/dp/B000FC0S...

Re: Software engineers should write

#78

"Even if nobody reads your essay, writing it will make an impact on you." After reading a post in HN ( https://news.ycombinator.com/item?id=5614689 ) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese. I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thi…

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…

I'll briefly exercise my pedant muscles to provide some technical terms for general interest:

http://en.wikipedia.org/wiki/Uses_of_English_verb_forms#Prog...

The first bullet is an example of past perfect progressive, which combines the past tense with the perfect and progressive aspects -- in other words, it describes that specific part of an ongoing action (progressive aspect) which has already been (past tense) completed (perfect aspect).

The second bullet exemplifies the past perfect, describing an action which has already been completed, without the additional progressive aspect to signify that the action is ongoing.

Both are correct, and would likely be understood to mean the same in colloquial usage; the only difference is that the former is somewhat more specific than the latter, in stating that the action is ongoing rather than leaving that to be inferred.

http://en.wikipedia.org/wiki/English_verbs#Third_person_sing...

This is a slightly unusual case in English, in that otherwise regular verbs almost always take a trailing (e)s in their third-person singular present-tense form. For example, conjugating to tell in the present tense:

1st person: I tell; we tell 2nd person: you tell; you tell 3rd person: he tells; they tell

Presumably this exception exists for historical reasons; why we keep it around, save habit, I have no idea. In any case, we do it with more or less all English verbs, save a few:

http://en.wikipedia.org/wiki/English_irregular_verbs#Verbs_w...

http://en.wikipedia.org/wiki/English_modal_verbs

Re: Software engineers should write

#79
post #67

Earlier quoted context omitted.

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.

Since you seem to appreciate corrections, it's a bit more natural to say "but sometimes I make some mistakes"

:D
Post reply on HN