Hacker News new | comments | show | ask | jobs | submit login
Software engineers should write (shubhro.com)
318 points by shbhrsaha 850 days ago | hide | past | web | 159 comments | favorite



"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 thing to do and it is the best subject to improve myself. It's not an easy task, and I do not feel I'm improving yet, but something in me tell me that I should keep doing it.


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 and a proof-reader).

Second: You're doing commas better than a lot of native english speakers. That's pretty impressive.

Third: There are a couple of grammatical/phrasing errors I'll tell you about in your comment. These are really common errors amongst people who learn English as a second (or Nth) language, and I'm not doing it to belittle you, but to help your stated goal of improvement.

I'm doing it since 09/22/2014

This is one of those wierd places in English where the verbs "to do" or "to be" combine strangely with tenses and idioms. I'm not so sure of the technical way of stating the problem, but here's a couple of examples of a more natural way to state it:

* I've been doing it since 09/22/2014.

* I've done it since 09/22/2014.

but something in me tell me that

This is a small one, and maybe a typo, but it is part of a pattern I've seen a lot. Again, not great at the technical grammar terms, but it should be:

* but something in me tells me that

(notice the 's' on tells).

Anyway I'm always impressed with people who can learn a second language well, and wanted to encourage it and help if can.


    > > I'm doing it since 09/22/2014
    >
    > This is one of those wierd places in English where
    > the verbs "to do" or "to be" combine strangely with
    > tenses and idioms. I'm not so sure of the technical
    > way of stating the problem,
If I'm not mistaken, the technical issue is that "I'm doing" is in the Present Progressive tense/aspect (an ongoing event in the present), which doesn't match having the past date there. "I've been doing" is in the Present Perfect Progressive tense/aspect (an event beginning in the past, but continuing into the ongoing present).


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 communicate with me, and I can return it by helping them at their goal.


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 <other language>".

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


I don't mind when I meet someone in normal daily activities that speaks English poorly. My thoughts on the subject mirror your own.

What _IS_ frustrating is dealing with a customer service representative in an overseas call center that speaks English poorly. How many man hours have been lost in forced communication with foreign contractors in an effort to save a few dollars an hour over an American counterpart? Also, those cost savings to a company like Comcast also damage our economy by not employing Americans in need of work. It's a double-whammy of frustration.


Your English is not "bad". There are some technical grammar issues you'll continue to work out, but the meaning in your writing is perfectly clear. That makes it pretty easy to overlook anything that's not quite correct in your writing.


Thanks!


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


:D


I know you said you write on a personal / private blog of your own to improve but if you ever wanted another person to look things over and help you work through some of the trickier parts of learning the language I'd love to help out!


It would be nice, but I haven't cogitated to do this before. I write too much personal things, maybe it is boring for other people, moreover I do not know if this is a good idea, once I will be too much exposed. First I would need to check what I wrote.


Well, I don't know what I have to offer to you in terms of a promise that I won't judge you or pry too deeply into your private life but I really have no good reason to do so. I will gladly share with you all that you want to know about me before we get started if you would like. I really just love helping people out, especially with technology. I started out working towards a career in education (with 12 years of experience) but changed over to programming and web development which is my current career. At some point I want to loop back around and teach some sort of technology discipline to come full circle with my original intentions.


Cogitated is a really obscure word in (modern) English.

Try "considered" or "thought about".


Oh, this is the problem when you do not have the vocabulary and use Google Translate to help.

"Cogitated" is very similar with the Portuguese translation "Cogitado", broadly used. And on Google Translate it appears as the first option.

I think that literature and travel are the keys to improve on this.


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.


"both sentences are completely intelligible"

This really makes me happy. I never left the country, and my first international travel will be to Melbourne in February/2015 where I will can test myself.


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.


For sure! But I can't think like that, because if I do I will be too much comfortable and stop trying to improve it.

I also sell some simple software overseas and, for doing business, if you have a bad grammar or a poor vocabulary, you loose points in the price negotiation. The other part can feel like they are negotiating with a hick.

Furthermore, everything you write on web will be technically forever, you need to delight the readers and poor English can annoy them, as I've already commented.


loose => lose.

http://www.merriam-webster.com/dictionary/loose http://www.merriam-webster.com/dictionary/lose

This is a common error for the natives as well so don't feel bad about it.

[Edit: I a word]


It often seems like most use on Hacker News gets this wrong (so it isn't surprising people pick up bad habits when learning English) and I regularly have to resist my inner pedant.

If the screw is too loose it could fall off and you might lose it.


There's a StackExchange site for English if you are unsure about the right way to say something: http://english.stackexchange.com/


There's also one specifically for those learning English: http://ell.stackexchange.com/


Native English speakers who get annoyed by mistakes made by non-native speakers deserve to be.


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


Another portuguese speaker here.

I think the reason why he used commas well (And that many other portuguese speakers use commas better than native english speakers) is that in portuguese you NEED to.

If you don't use commas properly in portuguese, you text can easily get excessively ambiguous, because of that schools here stress the comma a lot, I for example had in my fourth grade entire weeks dedicated to commas, and forgetting commas, even in non-langauge tests (example, in math tests) frequently resulted in some punishment (in math tests forgetting commas resulted into a loss of 0.1 points in the grade for each comma, out of the maximum of 10, thus if your math was correct enough to score 5, but you forgot 5 commas, you would instead score 4.5)


I think starting with a private blog is great advice, since it removes all apprehensions except for the "too little time" argument.


On the other hand, having other people read what you have written can be quite a thrill (especially if it becomes popular). Submitting your blog posts to HN and reddit/r/programming also can get you good feedback and alternative views (and, for that matter, mean comments too).


Have you seen http://750words.com/? It's an awesome tool that does exactly that and gives you some insights and game mechanics to make the exercise more interesting


Oh, very cool. Thanks, I just bookmarked it here.



> I'm doing it since 09/22/2014.

"I've /been/ doing it since ..." Concordo. Acho que deve continuar escrever. De onde você é?

I agree. You should continue to write. Where are you from?


Brazil.


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


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 say `reflected acoustic wave.' Say [echo]." Or, "Forget all that `local minima' stuff. Just say there's a bubble caught in the crystal and you have to shake it out." Nothing made him angrier than making something simple sound complicated.

via http://longnow.org/essays/richard-feynman-connection-machine...


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


There have been some good discussions around that story here a few times when it was posted.


Additionally, I've found that writing out the problem or solution in plain English sometimes helps me make the leap from conceptualizing to actually understanding.


Exactly. Writing helps an idea develop and sometimes change and move in ways we wouldn't have expected.


I enjoy also the Alan Perlis line, "You think you know when you learn, are more sure when you can write, even more when you can teach, but certain when you can program."

I have been endeavoring to get in the habit of writing about things that I learn. My main obstacle is the feeling that, even if I can write and explain the topic well, other people can too and already have; so why bother writing about it? But that misses the point -- or even two points.

The writing helps me; the fact that someone else wrote is irrelevant. Further, my writing, even if the subject matter is hardly original, might in fact help someone else: not everyone favors the same calculus textbook, or the same Python programming manual, or the same history of World War II. People enjoy different writing styles, different perspectives, even different fonts and page layouts. (I've elected against buying at least one book because I found the page layout excessively annoying to look at!)


When learning a new topic I try to explain it first to myself and then to others. Those iterations are very helpful in learning something new.


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 Algebra I teacher couldn't model the problem for me. He never explained anything, just expected us to memorize everything. We were never given real, tangible examples (contrived word problems don't count and never did!)...all we did was take stupid tests. My high school math experience was like a crash course in everything that's wrong with STEM education in America, and why we need to alter that if we're going to depend more on STEM in the real world.

In my opinion, programming has always been a form of writing. Just like songwriting is a form of writing. It's simply a different medium, and therefore you get a different result.

I might be looking at it from a different kind of lens though.


> 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 working on the web copy for a math book and trying to decide what to put above the fold to make the average Internet reader interested in math. So far the shortlist of pitches are (1) learn math easily because the book is short and written in a chill tone, (2) destroy your calculus and mechanics exams (for students), (3) get rid of math phobia (for English kids), and (4) gain modelling superpowers. So far I like (4) the best. What do y'all think? Any feedback would be much appreciated. ]


"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.


> a comical idea to try to market a book toward students these days

I agree with you generally, but if you compare with the current math textbooks (that students are usually forced to buy) you will concede there is a lot of room for improvement on the textbook side.

Also, while I think technology might be cool to play with, nothing beats the book as a medium for the transmission of information.


This one million times over.

I did very well at English at school, but failed hard at maths whilst freelancing from home after teaching myself PHP.

I really wish I'd engaged (and was taught) maths in the same way as I did with code - I remember feeling quite annoyed at the way I was being taught maths which was basically "when you see a question asked in this way, you answer it by following these steps". I think if I'd been taught maths through experimentation and having "projects" to solve in the same way I learned to code, I would've been quite a good maths student.


I always felt like school-level English classes were very hazy, muddy environments where you didn't need to have clear thinking and the structures (the English language mainly) didn't strictly follow any internal logic, opposite math. Peers got good marks for presenting half-baked ideas in inarticulate, thesaurus-abused essays, as long as they made sure to repeat their limp argument, cut up into a specified number of points, in the extremely redundant structure imposed by the curriculum (say what you're going to say, say it, then say what you said, with different synonyms each time) and use different joining-words or whatever term they used for obnoxiously putting "also" "further" etc. at the start of every new paragraph. Intellectual laziness was rewarded by the system, purposefully or not.

Those classes probably turned off a sad number of would-be good writers from learning how to write creatively, efficiently, or even reasonably. I had exactly one English teacher who was reasonable and only taught to these abominable standards as required by the state but let real writing be rewarded in other assignments; he understood the reality of the language and that the point of your writing should be moreso effectively articulating ideas, effecting desired emotional responses, or provoking thoughts rather than some nonsense a committee at the Department of Education decided is proper and that legions of English teachers across the country take to heart as dogma and revel in the sadism of. Otherwise, throughout the years it was splitting hairs over prescriptivist grammatical minutiae, the aforementioned ridiculous essay structure, memorizing obsolete Shakespearen-era "vocabulary words" that no writer writing for a living audience would even consider using, and going on about how any grammatical structure or word that appeared after 1900 is objectively wrong.

I could have put much less effort into them than I did and still gotten As but I preferred to use them as an exercise in trying to work good writing around the myriad deeply-rooted problems in how I was forced to present it. That's the only bonus point I can give to it as a learning environment.

English classes in college have just been the same disappointment with a different mask on for the most part, except for exposure to real research methods, but still lag behind the real world in forcing you to use non-internet sources.

Was the experience different for you?


That echoes my experience very closely.

I also disliked the emphasis on literary analysis. It so often seemed like contrived flimflammery crossed with psychoanalytic mumbo-jumbo. If tvtropes (or allthetropes) had existed back then, I think I would have performed much better on my English homework. After all, those sites do include the Jungian archetypes and the basic plots as a subset.

As it is, my high school English classes drove me far away from anything even remotely similar until a lifetime of reading fiction, a shameful amount of blathering on Internet message boards, and the exhortations of the "National Novel-Writing Month (NaNoWriMo)" organization convinced me to try to write a novel in November of 2012. Two years later, I have written 500 kb, with maybe 130 kb left to go before I snap it off and start the next one. Then there's also the matter of the default HTML stylesheet, continuity notes and timelines, the character, vehicle, location, and artifact indices, working hyperlinks, and testing the release version on all available e-reader programs and devices.

As for my old English teachers, I bite my thumb at them, like Sampson. I give them the fig, like Vanni Fucci. And just as golf is a good walk, spoiled, English class is a good read, ruined. Even with those ancient cultural references rattling around my bonebox, I find that an increasingly large fraction of my memes are drawn from television, film, music, video games, and popular web sites, and a vanishingly small portion from the old literary canon.

That's how I know that the Belmonts love Devo. If you understand why, you probably won't need to thank an English teacher.

All I really ever needed was a pile of books that I enjoyed reading and a copy of Strunk and White (minus the part about always putting sentence punctuation inside the quotes, because that's just madness). What I got was about 10 years of pedagogical torture that discouraged me from trying something that turned out to be a fun hobby.


Somewhat related is a recently published book by Angus Croll called If Hemingway Wrote Javascript[0]. It's not so much about Javascript as it is about the writing styles of great authors and the expressiveness inherent in writing code.

[0] http://www.nostarch.com/hemingwayjs


Thoroughly agreed. As a developer who spent a lot of time studying humanities, arts and other disciplines requiring constant writing for grant submissions, essays, etc. a lot of skills required to be a good developer become invaluable for a dissertation and the other way around.

  >  A core skill in both disciplines is an ability to think clearly. The best software engineers are great writers because their prose is as logical and elegant as their code.
Personally, I found that combing through my text again and again and again to cut down on unnecessary words, combining similar ideas ideas and clarifying points made a huge difference, and was very much akin to optimizing software. It was generally something other students didn't really bother to do and their writing greatly suffered from it.


I recently worked as an expert witness and had to write a report, I haven't written anything since University ~15 years ago. Writing a technically accurate report about source code for a non-technical audience was amazingly difficult. It was fun, but stressful. Each sentence has to be able to withstand a cross examination, sometimes it took hours to write a single sentence.

I'd do it again, and I recommend anybody that gets the change to do it as well.


> Personally, I found that combing through my text again and again and again to cut down on unnecessary words, combining similar ideas ideas and clarifying points made a huge difference, and was very much akin to optimizing software.

I learned these optimization techniques later in my grad school studies (a very critical adviser helped), never learning how to really write as a CS undergrad. Now I am the go-to guy for paper editing, and I find it frustrating that I can't seem to teach this to those I help write papers.


> combining similar ideas ideas

I can't decide if that was deliberate or not.


Highly agree with this - I am baffled why the humanities aren't taught this way in US high schools. Writing always seemed difficult to me then, but upon taking my first college class which had lots of essay writing, it dawned on me that making a persuasive argument was the most important part of an essay. This has much in common with the critical thinking touted in the hard sciences & mathematics. If English was taught this way in K-12 education, instead of enforcing arbitrary rules such as page length & word count, I would have done immensely better.

I got the important takeaway from that experience, but many people do not, and it is a shame.


Thanks for posting this, it is very timely for me. I have been a forum lurker for most of my life. I visit Hacker News almost everyday but seldom do I post a comment and I have never submitted an article. Same with Facebook, I'm mostly a lurker. It is my New Year's resolution to start writing and contributing more to the online communities I visit. In fact I just finished my first draft of a blog about my experience using Angular, LokiJS, and Ionic to make offline apps. Hopefully in the next day or two I will publish it on my blog and maybe even submit it to Hacker News. Your blog posts encourages me to keep at it. Thanks.


If you do submit to HN, don't get too tied up in whether it gets any attention or not. Plenty of quality submissions slip by without rising to the front page.

That said, it's really fun and enlightening to see a high-quality conversation develop around something you've written. Keep writing, submit your work on occasion, and enjoy the process.


Hey software engineers, write some m*ther f!cking documentation! Don't tell me it goes out of date, at the very least a module level, architectural overview is better than nothing, and should remain relevant past your tenure.

/rant


How do you feel about the saying that code itself should be as good as documentation?

I personally prefer to read the documentation while skimming the code as well but sometimes, when I am under the pressure of having to deliver something, I absolutely despise not having proper documentation so I tend to agree with you.


Code doesn't capture intent in many critical cases, so figuring out what a piece of code is supposed to do is different from figuring out what it does. This is true in part because there are very different levels of abstraction involved.

To take a trivial example:

norm = sqrt(x[0]2 + x[1]2 + x[2]2) x[0] /= norm x[1] /= norm x[2] /= norm

This could be described as "take the square root of the sum of three values and then divide each value by the result" or "renormalize a vector". The latter is by far the more meaningful and useful description because it is presented at the level of abstraction that the user is likely interested in.

You could say "well why not create a function called 'renormalize_vector' so it would be self-documenting?" Fine, but now you have a function call per renormalization and that has a cost that may be unacceptable. For many simulations renormalizing vectors with a norm near unity is a big overhead, to the extent that I've written custom code to handle that special case and implement it as a macro that I could call "FAST_RENORM_NEAR_UNITY"... but what does "near unity" mean? And what trade-offs went into the design choices? What code isn't there because I tried it and it didn't work well?

People who advocate self-documenting code generally talk as if self-documenting techniques come at zero cost (adding a function call is an unacceptably high cost in some cases) and that the code that exists adequately captures all the thinking that went into it (it does not and cannot.)

So while I'm all for as much self-documentation as possible, any non-trivial code is going to require additional documentation to a) describe the purpose in high-level terms and b) capture the alternatives that were rejected and why.

Unfortunately, for open source projects especially, there is a law of documentation that says power*documentation=constant, so the most powerful code has the worst documentation, and there are projects with great documentation that simply don't do much.


This a hundred times. Comments should always be about intent; never about what's actually happening (the mechanistic description). I don't need help understanding the code as read; I need to know WHY the code was written. So I can debug, follow code paths, skim.

A further advantage: such comments have longer halflives. A rewritten method may still have the same purpose long after all details are changed.


> but now you have a function call per renormalization and that has a cost that may be unacceptable.

I would go for the function, and pass along Knuth's advice about premature optimization. If you're writing at such a low level that function calls actually aren't acceptable, go with a comment "// renormalize vector." Your instinct should be the function though. I bet there is more than one vector normalization going on in this hypothetical codebase, and that line looks pretty typo-prone.


> How do you feel about the saying that code itself should be as good as documentation?

Not him, but I'll take a crack at it: adorable, high-minded, and wrong. Most people are not going to walk through your code to grasp it in its entirety; design, and document, accordingly.

At the very least, you should have exhaustive, well-considered, commented unit and integration tests to demonstrate its use cases and (foreseeable) failure modes.


>> How do you feel about the saying that code itself should be as good as documentation?

The truth is, 95% of developers do not write readable code. But I've been doing this for a while, so I can follow pretty much anything. It's the shear volume of legacy code in the typical code base thats the problem.

What kills me is dead code that you don't know is dead; hundreds of class files, dto's, booleans passed around to control processing that are always false now, because that alternate path is no longer used. And protocol messages, oh god the hundreds of protocol messages, but we only use 10 now.

Edit; I've been the hero more than once documenting stuff like the above.


The code doesn't document your intent. There's no way to tell if something weird is a bug, or a feature for an edge case that was never written down.


Variable and method names can do that, and are more likely to be kept up to date than comments.


Standard HN car analogy time. "Look at the code" is like telling a car mechanic trying to replace a part to look real closely at a high res pix of the factory, instead of reading the Haynes manual.


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.


I write a blog[1] and I try to add good documentation to my open source project[2], but I recognize that I'm in the minority. One benefit I get from writing, even though I don't get a lot of readers, is thought refinement. I usually send my blog posts to friends and family for help on word choice and better delivery. Even though Steve Jobs said people don't read, I think reading and writing are critical because you don't always have a camera or a microphone to get your message across.

[1] - https://blog.joeblau.com/

[2] - https://github.com/joeblau/gitignore.io


>> "Even though Steve Jobs said people don't read"

Source on this? As a general statement that sounds kind of ridiculous. I would have thought people are reading more than ever considering how much of the internet is text. Also a little strange considering Apple runs a bookstore.


It was from the New York Times [1] they asked Steve about the Kindle reader.

> “It doesn’t matter how good or bad the product is, the fact is that people don’t read anymore,” he said. “Forty percent of the people in the U.S. read one book or less last year. The whole conception is flawed at the top because people don’t read anymore.”

[1] - http://bits.blogs.nytimes.com/2008/01/15/the-passion-of-stev...


So it seems like he meant books specifically. Still strange considering he then opened iBooks but I guess this was a case of Apple being on the back foot.


Wow, gitignore is an OSS project?! Didn't know this. Are you looking for collaborators? Love your project and have been looking for something to tinker with on free time. Kudos for great work!


The gitignore.io site is OSS as well as the gitignore template list maintained by GitHub. If you want to collaborate that would be cool, although there isn't much the site does :). All I've been doing recently is merging pull requests and updating submodule.


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[2], unsurprisingly designed by a novelist who is also a theoretical physicist. Even with The Hero's Journey, there's a surprising amount of well-understood structure behind every story.

[1] http://www.amazon.com/dp/B00QPBYGFI [2] http://www.advancedfictionwriting.com/articles/snowflake-met...


The pistol on your novel's cover is a CZ-75. It's not an unknown gun by any means, but it's relatively uncommon in real life; sushi to the hamburger that is a Glock or a Beretta. Despite this, it's a common choice for infographics where just "a gun" is needed, and I can't for the life of me figure out why.

I'm curious - do you know why that particular pistol was chosen for your cover?


Interesting, never thought of figuring out the model!

The cover was made by a freelancer I found on 99designs.com (I'm really happy about that experience, BTW - and I have nothing to do with them, I just liked the service). The pistol looks good and the image was royalty-free, which is probably why the freelancer chose it.

But in retrospect you're right, I should have checked. The only pistol specifically mentioned in the novel is a "H&K" (not even the model), but there are many other anonymous ones. This CZ-75 could be one of these :)


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...


Wow, fantastic work :)

I agree with what you're saying... a novel is the end product, a screenplay is a blueprint. It took me 4 years to write the novel (admittedly very on and off) and ~3 months to write each of the screenplays. Hopefully my next novel will be faster.

What was your experience of writing both formats in terms of time and effort?


Thanks! :-)

My novel took 5+ years of blood, sweat and re-writes.

Writing a passable screenplay took five days, about six hours a day (evenings 6 - midnight). I don't expect I'll ever sell it, but I'm as certain as anything that it's better than a lot of screenplays that have been sold.

I'm mostly a poet, and love structure. Once I understood the structure of a screenplay, it just happened. Novels in contrast are these huge unstructured messy awkward wobbling teenage flailing morasses. The lack of structure, the lack of constraint, the lack of form is something I struggled with for a long time, and while I expect my next effort won't be quite as painful, I don't ever expect it to be easy.

"Form is liberating", as the engineer's proverb goes. Novels don't have it, and are therefore much more work.


Congratulations on getting the book written and on Amazon. I hope to follow in your footsteps in the coming year.

Like you, I'm fascinated by story structure, the hero's journey, and the mono-myth. And I've struggled with creating something less than flat characters.

I've read the Snowflake method, and parts of it definitely work for me. Another book that I highly value is Dwight Swain's Technique's of the Selling Writing. This was one of the first books that I read on writing fiction, and I still think it's one of the best. I would also recommend Baboulene's, The Story Book, for it's discussion on subtext.

Unfortunately for me, the focus on technique left me not only with flat characters but also a severe case of writer's block. However, I may have found a solution to both problems in John Dufresne's Is Life Like This? Dufresne advocates a more organic, even serendipitous, approach to story creation. For him at least, the results can be wonderful (read his Love Warps the Mind a Little, or his short stories in Johnny Too Bad), and for me, it's got me writing (finally!) and seeing my characters as something more than just cardboard cutouts. Like anything else, it's not for everybody, and YMMV.

Good luck, and keep writing!


Best of luck with your book :)

The first book I've read that really resonated with me about giving life to characters is The Screenwriter's Bible by David Trottier. BTW, I've read a lot more books about screenwriting than about writing novels, but I believe both apply... stories are stories.


Great point! Completely overlooked that aspect.


I've always admired the writing style in the Economist: http://www.economist.com/styleguide/introduction


Because of my own ignorance, I'd assumed The Economist Style Guide was another tome mainly full of usage rules. Having actually looked at a bit of it now, it seems much more accessible and useful than that.


The title "Software engineers should write" could mean either "Software that engineers should write" or "Software engineers should also write". I didn't know which until I clicked through to the article. It's OK to use "Software engineers should write" when speaking because we'd use a different stress pattern to resolve the ambiguity, but when writing, the extra word (whether "that" or "also") is needed, especially in a headline. I guess making writing unambiguous is one of the skills one picks up when one writes a lot.


Andy Rooney complained about people who say, "I'm going to write a novel when I retire" but don't say, "I'm going to do brain surgery when I retire."

I think he might mean that writing for human consumption can be harder than most people think.


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 possible worlds give you guidance and encouragement. And while there are those who will make fun of you for not being in the "real world" they will also envy you a bit and respect what they presume to be your unusually large cranial capacity. That kind of ego-boost helps. It's positive feedback on how you're spending your life.

Building any new application is daunting, but even as the technical lead on a computer-assisted surgery system that went from nothing to giving surgeons real-time image guidance in the OR, I had investors, domain experts, and my team all giving me feedback and support and help in dozens of different ways.

Writing a novel is incredibly lonely. You do it all by yourself, every day, for years on end, with no positive feedback from anyone. I don't ascribe much value to writing workshops, which I think exist solely as an ameliorative to the profound loneliness of the novelist's life. A first reader or two who you can trust to give you small pieces of critical feedback on early drafts is what you really need.

Workshops tend to produce work that feels workshopped: stripped of individuality and weirdness for the sake of responding to the demands of the loudest--and frequently most conventional--voices in the room. If you listen to the quieter voices you'll find that some people love what others hate. You have to write to please yourself, and that is almost pathologically egotistical. Most people simply aren't arrogant enough to say, "My artistic vision is so important to me that I'm willing to spend thousands of hours entirely alone doing enormously difficult work to realize it."

The technical complexity of novels is also unparalleled. My PhD was in an area where the data were a mess and the theories proved the truth of the maxim that "theorists have never had any trouble explaining the results of experiment, even when those results later proved to be incorrect". The phenomena driving the whole field later turned out to be an artifact of borderline-fraudulent statistical analysis by the team who "discovered" it. So finding a coherent narrative through the conflicting claims in the literature was extremely challenging, on top of the usual difficulties of performing a novel and interesting precision measurement to test one particular theory. But moving a handful of characters through a series of events and choices that carry them toward a satisfying climax is at least as difficult, and made more-so because there are no fixed points. You can do anything. Without constraints, the writer's discipline is the only thing keeping the narrative whole.

Furthermore, a novel is "technical complexity all the way down". Every sentence, every word, every punctuation mark is an opportunity to screw up, to make a mistake that will jar the reader out of the continuous dream of the story. I've been writing since I was in my early teens, and thirty years of practice was still barely enough.

Most novelists will tell you that the first novel is the worst, because there's really no way of understanding the process without doing it, and I agree with that. If you think you want to write, you should start now, at whatever age you are. Get that first novel behind you. Write it. Re-write it. Edit it. Polish it. Publish it. It'll be worth it, if that's what you really want to do with your life. And technical people really should write, both fiction and non-fiction: it is a great way of exploring and ordering your ideas.

All that said, was it worth it for me? Definitely. I learned more about writing and the ideas I was exploring than I could have any other way. Whether the end product is worth it for anyone else is left as an exercise for the interested reader: http://www.amazon.com/Darwins-Theorem-TJ-Radcliffe-ebook/dp/...


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.)


Sure, that's fair. I guess my point was that it's hard to produce something of value without some kind of practice before hand, in some form. (Maybe short to novel isn't a perfect transition, yes.)


It's been said that a programmer's brain is more akin to that of a writer than a mathematician, allegedly because learning programming languages is much like learning a language - the same areas of the brain are involved.

From http://www.huffingtonpost.com/chris-parnin/scientists-begin-...

> Scientists are finding that there may be a deeper connection between programming languages and other languages then previously thought. Brain-imaging techniques, such as fMRI allow scientists to compare and contrast different cognitive tasks by analyzing differences in brain locations that are activated by the tasks. For people that are fluent in a second language, studies have shown distinct developmental differences in language processing regions of the brain. A new study provides new evidence that programmers are using language regions of the brain when understanding code and found little activation in other regions of the brain devoted to mathematical thinking.


I was always crap at creative writing in school, but I am a decent programmer. I personally don't find them very comparable at all.


Reminds me of Steven Pinker's recently-published book on how to write well, "The Sense of Style" [1]

Pinker uses software terms to describe good writing: convert a _web_ of ideas into a _tree_ of syntax into a _string_ of words.

[1] http://www.amazon.com/dp/0670025852


I interpreted this headline as "Software that engineers should write," as in "Engineers, please make the following bits of software."

Which in a way helps prove one of the article's points: writing and programming are alike in their need for precision and clarity. :)


There are times I wish I could go back to my younger self and explain exactly this. Unfortunately it took me almost a decade as a software engineer before I realized there was a career barrier without being able to communicate effectively when writing or presenting.

It's possible to stay as an average engineer for a long time, but if you want to try being an Architect, then at least 50% of your time is spent writing or public speaking. If you want to be an engineering manager, that's over 90%.

Fortunately a company I used to work for believed pretty strongly in cultivating these "soft skills", so they incentivized things like Tech Talks, and covered the cost of courses like Dale Carnegie.


How did they go about incentivizing tech talks?

Have you written anywhere about the things this company did?


The TechTalks had a few purposes. First, it was to spread knowledge within the company about what other groups were working on and how they were doing it. Second, it was for recruiting new developers. (If the talk went well internally, then we were often asked to do it again for local developer groups or meetups at area colleges.) Third, it was part of the career development they tried to do - trying to create good Architects that knew the business and the problems that needed to be solved.

The talks were incentivized as part of the bonus structure. If the company did well, and you completed your goals, then you could get up to X% of your salary as a bonus. (Also, they usually included free lunch)

The technology and the people at that company were really great to work with - I probably got more experience in one year there than five years at any other company. Unfortunately it was in the advertising business, so many of the business practices were slimy and cutthroat. (It seemed like every month we had a crisis where either Google, Microsoft, or Apple didn't like what we were doing and wanted to shut it down.)


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!


I completely agree with this. I've started blogging for my work on some of the things that I'm actually writing code for.

I've actually found that it helps me think about more of the big picture stuff. In writing my first post about one of our APIs [1] I actually realized that there was a small omission in how we designed it.

[1] http://exosite.com/real-time-device-communication-part-1/


Writing is never easy for me even in my first language. I guess I am one of those "math kids", but some part of me wants to write, to express myself, to make an impact. I do become better at writing after a few blog posts in Chinese, and I will start to write in English, because I think English is such a beautiful language and after so many years of studying, writing might be the way for me to truly understand and use it.


If you enjoy writing, then write. If writing, or improving your writing, helps you achieve the things you want to, then write.

But don't feel you "should". Essays are a bit like code - but if you want to get better at coding, you'll do better practicing coding than practicing essays. Likewise if your goal is "impact"; blog posts, particularly general ones like this, are ten-a-penny - even really good ones. Whereas really good software libraries are rare, even now - and you're more likely to write a specialist software library, with a small audience but one for whom that library is vital, than an equally specialist blog post. And while writing about something may clarify your thoughts, it's nothing next to setting that thing down in code.

Once again, do what you enjoy. If you like to paint, paint; if you like to make music, make music. But if you'd rather just code, or even just watch TV (the very epitome of unproductive wastefulness - but the typical blog probably achieves very little more), that's fine too. Don't let anyone tell you you shouldn't.


I think this is one of the main benefits I find on HN. Not only does this give me an intelligent, well educated community to talk to, but most often the community shares my hobbies and interests.

I think being able to write is extremely important, but I think the rhetoric behind writing is just as important, if not more important. When you write in a community or forum, like HN, citing your sources and defending your arguments is more important than on a blog, because if you don't, your voice simply won't be heard as loudly.

Contrast this with clickbait blogs, or blogs that simply write for shock, it because clear that having a humorous or convincing writing style is almost as important as being able to argue your point, or convey a complicated idea. However, in my mind I find the latter a far more important skill in the long run.

So yes, software engineers should write, but also don't forget to do some 'code' reviews.


I just published my first kindle short story: http://www.amazon.com/dp/B00RA3UD20

Also, related link on writing: https://news.ycombinator.com/item?id=8793024


<rant> 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. </rant>


To paraphrase Knuth, "programming is explaining to another human being what you want a computer to do."

Should you take it to the extreme Knuth did with Literate Programming? I personally don't. But, once I've successfully explained to the computer what it should do (my program works) I look for ways to better communicate what it's doing (my program is readable). In many cases that's harder than solving the technical problem at hand.

Concision and simplicity seem to be the key to that. I agree with the author that "like good prose, good code is concise," although for prose that's more a matter of taste. Otherwise we'd all be reading a lot more Hemingway.


I like this quote (from Joan Didion):

"I don't know what I think until I try to write it down."


There's a similar one from Churchill when asked by a frustrated colleague to get to the point: "How can I know what I think until I hear what I say?"

I think a lot of writers are like this: we are painfully aware of our ignorance, our uncertainty, our lack of belief. The struggle to articulate our beliefs is a struggle to form them. Non-writers often seem to "just know" what they think, which is to me quite remarkable. But they also frequently lack the tools to analyze their beliefs and how they are constructed, because they never have to go through the slow and painful process of figuring them out.


Every programmer should read Strunk & White's The Elements of Style.

Its emphasis on clarity and concision translates directly to code, both in terms of algorithmic efficiency and human readability, comprehension, maintainability, etc.


Totally agree with this post. I was a math/english kid. Still am. I went as far as writing a whole book about computer science:

http://browndogsandbarbers.com/


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


Software engineers are out of focus. The focus is not the code, the focus is the end users. Great code that functions without logic (most of MSFT) is generally useless. Users should not have learn to a new vernacular nor change their logic use patterns to use a new software. Software that fails to reach users without extensive documentation is useless no matter how great it is. Users should do the dreaming; software engineers should be limited to "making it so". Moral to this article: anyone who can write prose can write code....


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.


I can't agree more. I remember the remarks of my fellow Computer Science colleagues at uni when I was off to my business courses (I did a double degree): all the reading, the essays, they were looking at it as the 'easy' , 'boring', 'irrelevant' things - because what can be more important than writing code? Well - it helped. It helped a lot. How are you going to sell whatever it is that you're building without putting together a good description of your product or a convincing sales pitch?


Where I grew up the distinction didn't happen until high school, and even then there was a large overlap between AP Calculus and AP English. Computer Science was a different beast - we were a subset of the Math nerds that didn't necessarily get into English due to the imprecision.

The irony is that the precision of CS makes us better writers because we can see the inconsistencies. (How many requirements documents can be interpreted multiple ways?) Between undergrad and grad the Math/Verbal spread on my standardized tests flipped.


I love writing, especially technical documents. It feels like the best parts of creative writing (since writing down what you're going to do is somewhat like fantasy anyway), but without the wishy-washy unreferenced opinions of non-technical writing. I always use citations, write a review of the literature, describe my solution, how I'll implement it, and what the risks are. I think I actually enjoy it more than the technical work sometimes, and it's certainly made my technical work much better planned.


> Software engineers should write because it promotes many of the same skills required in programming.

The problem with writing is that you usually do it by serializing your thoughts in one go. Programming on the other hand is an activity where you almost randomly jump from one point to the other.

> Code and essays have a lot more in common.

What I hate about writing prose, is that you are expected to use synonyms all over the place. If you use the same word in two subsequent sentences, this is considered "bad". With programming, I have no such problem.


>The problem with writing is that you usually do it by serializing your thoughts in one go.

Depends on the person and the circumstances. I admit that I tend to write linearly as a first pass and the writing is often an act of discovery--although I generally have some idea of my (intended) destination when I begin. That said, I'll often craft sections semi-independently and "glue" them together after the fact. I think I see more structural and process similarity than you do.


> The problem with writing is that you usually do it by serializing your thoughts in one go. Programming on the other hand is an activity where you almost randomly jump from one point to the other.

It's startling how much I write the exact same way I code, namely by jumping around from place to place. It's more important that your written thoughts deserialize linearly than it is for you to serialize them that way.


>If you use the same word in two subsequent sentences, this is considered "bad"

It depends. We are explicitly taught to do this in philosophy papers - be clear about what your terms mean, and then always use the same term when you mean the same thing.


Many people might have already seen it, but I thought it'd make sense to mention DHH's talk at RailsConf either way.

In his talk, he is coining the term "software writer", which goes one step further and motivates a style of programming which prioritizes clarity of code over alleged technical superiority. Very opinionated, but recommended nonetheless: https://www.youtube.com/watch?v=9LfmrkyP81M


When I first moved to the valley (as a writer) I found I had so much in common with my new friends who were software engineers. Our personality traits were similar, and we wore hoodies and stayed up all night. I'm actually a brilliant math student but writing was the skill set I pursued. I'm really glad you wrote this -- there are so many fascinating parts of software engineering and bright minds whom I would love to learn more insights from!


Thinking back, I was neither.

I wasn't good in math, languages or anything in elementary school.

I didn't want to be there and always played "sick".

This just got a little bit better, when I left elementary school and switched 2 schools afterwards. Since the second school was a lot easier than the first, I got better grades without doing anything.

But I never got really good at anything at school, better in Science than in Humanities, always a B- on average. Even my degrees got that rating...


It is probably not worth extrapolating from elementary school performance. And it is probably even less useful to use grades as a measure of success at anything other than doing schoolwork.


Funny thing is, I got this you're A or B impression still.

Developers and designers, tech and sales, front- and backend...


Great article. As somebody who has always identified with the "math" kid, I've never dreaded nor disliked writing. In fact, I often have the urge to write. My biggest issue is confidence in my vocabulary. After years of schooling for engineering I feel as though my non-technical vocabulary hasn't progressed much since high school and always seems to fall to the bottom of my personal studies.


I believe vocabulary is one of the least important facets of writing. Prose is combinatorial. Even with a smattering of words, there are a near-infinite number of novel, expressive ways they can be combined.

It's rare that a great concept can't be expressed from the lack of a word or two. You almost always need full phrases and sentences to get an idea across anyway.

Also, vocabulary is one of the things most amenable to being improved during editors. I've heard of lots of famous others whose first drafts have "<better word here>" all of over the place. If you think there's a better word than springs to mind, finish your thought without it. Then, crack open your thesaurus later and come back and sprinkle some word seasoning in there.


As a writer, software product manager and dad who is trying to encourage his girls to learn to code, I really enjoyed the post as it highlights the similarities between programming and writing - and the fact that communication is truly one of the most critical skills a developer or anyone can have.

Now, I just need to learn a programming language and start coding so I can improve my human/computer communication skills :)


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.


I've been saying this for so long. I realized at some point that the classes that had the greatest positive impact on my programming ability were always writing classes. Writing seems to engage the same part of the brain in a way that's just different enough to feel different. Even editing is a good lesson in refactoring. I'm always weary of any engineer who can't write.


Yes. Yes! As a developer myself, the value of writing has been earned 1,000 times over.

If you need some help getting started, try this: http://john.do/today/

And, here's my thoughts on the importance of a Developer's Blog: http://blog.desk.pm/dev-blog/


For all the software engineers who want to write: https://www.gitbook.com


I completely agree with you, writing does help the software engineer think clearly. I recently started writing short poems and it has helped me think better when writing code..

I also believe that the engineers should write code everyday as well.. many of the engineers take at least a day off from the week and it somehow reset's mind a little


I practice this by writing API documentation. When I can't seem to write code or want to take a break, I write out a plan of what I'm going to do or flesh out the documentation. Not only does it provide me a rigid framework for what I need to code, but it helps the user using my product as well.


This title is a bit too vague; I read it as "Software [that] engineers should write" thinking it was going to be an exposé on how software engineers could better spend their time. Maybe change it to something like "Software engineers need to write, not just code"


"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)



Software engineers do write. You see their rants on hacker news all the time. Most of the time, they write about why some programming language is either good or bad.

Maybe software engineers should write less.


I find myself uncertain about the thesis. Code that is clear and expressive to a human should not be assumed to also be efficient and optimal for a computer.

As writers say, know your audience.


"Code that is unreadable by other engineers, even if it's functional, is bad code."


Code is designed to solve problems. If someone can't read your code, they are going to have a hard time using it to solve their problems. If you don't document edge cases, modes of failure, intent and methodology... then it is worse code than it could be. Somebody won't be able to use it because they won't be able to tell if it solves their problem.

A few weeks ago I read a quote about someone saying that good code should be 'self-documenting' and that it should be obvious what it does. This is a red herring -- it assumes you wrote code that works perfectly. If there is a bug in your 'self-documenting' code, then how is someone supposed to know if it is wrong or not?


I didn't see what you are seeing in the thesis. There was nothing that said that the sole end goal of programming is to be expressive to humans (whether those humans be yourself, other coders or end users).

As for audience, when coding you can consider your audience to be both humans that follow you, as well as the machine it is running on.


One of the ideas mentioned is that code that's readily understood by humans is code that will be efficient for computers. I'm not sure I agree with this.


As well as your future self, weeks from now, to avoid having to say 'What the fuck was I thinking when I wrote this?'.


True enough - but code that humans can't read is far more difficult to debug, to profile, and to optimize. Efficiency can be improved after the code is working, but improving readability on a prematurely-optimized codebase frequently involves `rm -rf`.


> Code that is clear and expressive to a human should not be assumed to also be efficient and optimal for a computer.

Yes, but most of the time it's more important that a human can understand it easily than it is for it to be the most efficient code in the world.


I think programming might help you write very prose pieces, but there is still a lot more to literature that remains very artistic.


I'm an English kid but I'm a Computer Science major, to. This is why I think I'm on the wrong path.


"Even if a project doesn’t require communication"

Every project requires communication.


they should do it all. there is nothing they should not do.


I agree with the article's arguments. I've been programming since age 10. Doing creative writing almost as long. As an adult ended up doing software engineering as my career. But wrote and published a fiction book two years ago (The Dread Space Pirate Richard, an adventure comedy), close to finishing its sequel (The Man in Black) and also have my first technical book (Software Performance & Scalability) under development. Also written a screenplay and many short stories.

I've found a lot of overlap, in thought process, between programming and writing. Also with music and math. Leverage everything that helps, I think.


Come to http://www.kuro5hin.org/ - most of us are software engineers; all we do is write.

Before submitting a story, spend some time introducing yourself to the community - post diaries, as well as reply to the diaries and comments of other kurons.


Indeed a very good though sir. I am a Electronics engineer who works in a IT software industry but i love to write down my thoughts and share my knowledge on the very platform of blogging at www.quikrpost.com


Don't tell me what I should do. It's condescending. You don't know me. You should learn how to write without adopting a tone of presumptuous condescension.


Software engineers should write at thewinnower.com. Here's why:

1) their writings will be preserved with the same power that libraries afford traditional scientific publishing

2) They wont just be blogging, they will be publishing.

3) They can assign a digital object identifier (DOI) at their discretion making their work "count" in the scholarly literature.

4) Their blog will be automatically formatted as a PDF.

5) https://thewinnower.com/papers/science-the-pursuit-of-the-tr...

6) https://thewinnower.com/papers/making-scientific-blogging-co...




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact

Search: