13 ms·

Software engineers should write

318 points by shbhrsaha 12y ago

edpichler 12y ago
"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 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.
- rdrey 12y ago
  I think starting with a private blog is great advice, since it removes all apprehensions except for the "too little time" argument.
  - henrik_w 12y ago
    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).
- ionforce 12y ago
  > 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?
  - edpichler 12y ago
    Brazil.
- sophacles 12y ago
  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.
  - edpichler 12y ago
    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.
    - sophacles 12y ago
      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.
- IndianAstronaut 12y ago
  As someone trying to learn Portuguese, I should probably start writing in Portuguese.
- bdotdub 12y ago
  Have you seen http://750words.com/ 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
  - edpichler 12y ago
    Oh, very cool. Thanks, I just bookmarked it here.
- Reef 12y ago
  http://xkcd.com/1179/ http://xkcd.com/1179/ please :)
kalid 12y ago
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.
- debaserab2 12y ago
  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.
  - therealdrag0 12y ago
    Exactly. Writing helps an idea develop and sometimes change and move in ways we wouldn't have expected.
- ivan_ah 12y ago
  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/ http://longnow.org/essays/richard-feynman-connection-machine...
  - azeirah 12y ago
    That's an absolutely excellent story. I can recommend it to anyone on this site.
    - sophacles 12y ago
      There have been some good discussions around that story here a few times when it was posted.
henrik_w 12y ago
I like this quote (from Joan Didion): "I don't know what I think until I try to write it down."
- tjradcliffe 12y ago
  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.
euphemize 12y ago
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.
- trentmb 12y ago
  > combining similar ideas ideas I can't decide if that was deliberate or not.
- FigBug 12y ago
  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.
- seanmcdirmid 12y ago
  > 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.
Kalium 12y ago
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.
- al2o3cr 12y ago
  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`.
- azdle 12y ago
  > 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.
- aswanson 12y ago
  "Code that is unreadable by other engineers, even if it's functional, is bad code."
  - Retra 12y ago
    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?
- robbrown451 12y ago
  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.
tomphoolery 12y ago
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.
- _neil 12y ago
  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 http://www.nostarch.com/hemingwayjs
- ivan_ah 12y ago
  > 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. ]
azdle 12y ago
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/ http://exosite.com/real-time-device-communication-part-1/
jobu 12y ago
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.
- coolsunglasses 12y ago
  How did they go about incentivizing tech talks? Have you written anywhere about the things this company did?
  - jobu 12y ago
    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.)
Bahamut 12y ago
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.
ggambetta 12y ago
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 http://www.amazon.com/dp/B00QPBYGFI [2] http://www.advancedfictionwriting.com/articles/snowflake-method/ http://www.advancedfictionwriting.com/articles/snowflake-met...
- shbhrsaha 12y ago
  Great point! Completely overlooked that aspect.
- presidentender 12y ago
  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?
  - ggambetta 12y ago
    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 :)
- tjradcliffe 12y ago
k__ 12y ago
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...
- Retra 12y ago
  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.
- k__ 12y ago
  Funny thing is, I got this you're A or B impression still. Developers and designers, tech and sales, front- and backend...
pluc 12y ago
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-looking-_b_4829981.html 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.
- collyw 12y ago
  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.
marktangotango 12y ago
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
- las_cases 12y ago
  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.
  - eropple 12y ago
    > 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.
  - gaius 12y ago
    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.
    - lmm 12y ago
      Variable and method names can do that, and are more likely to be kept up to date than comments.
  - VLM 12y ago
    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.
mathattack 12y ago
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.
emcarey 12y ago
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!
friendcode 12y ago
For all the software engineers who want to write: https://www.gitbook.com https://www.gitbook.com
mkramlich 12y ago
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.
joeblau 12y ago
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/ https://blog.joeblau.com/ [2] - https://github.com/joeblau/gitignore.io https://github.com/joeblau/gitignore.io
- mirkoadari 12y ago
  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!
  - joeblau 12y ago
    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.
- k-mcgrady 12y ago
  >> "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.
  - joeblau 12y ago
    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-steve-jobs/?ex=1358226000&en=dc35254b0fcd5490&ei=5090&partner=rssuserland&emc=rss&_r=0 http://bits.blogs.nytimes.com/2008/01/15/the-passion-of-stev...
searine 12y ago
What a circlejerk.
henryw 12y ago
I've always admired the writing style in the Economist: http://www.economist.com/styleguide/introduction http://www.economist.com/styleguide/introduction
- LVB 12y ago
  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.
harshbhasin 12y ago
I just published my first kindle short story: http://www.amazon.com/dp/B00RA3UD20 http://www.amazon.com/dp/B00RA3UD20 Also, related link on writing: https://news.ycombinator.com/item?id=8793024 https://news.ycombinator.com/item?id=8793024
sigil 12y ago
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.
exacube 12y ago
I think programming might help you write very prose pieces, but there is still a lot more to literature that remains very artistic.
deleted 12y ago
[deleted]
alexggordon 12y ago
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.
deleted 12y ago
[deleted]
VLM 12y ago
Interesting discussion point, Larry Wall, linguist, invented a programming language that is not exactly considered stylish at this time. Implications?
- rimantas 12y ago
  Being linguist does not make you a good writer, just as being theologician does not make you a saint.
0xdeadbeefbabe 12y ago
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.
- tjradcliffe 12y ago
  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/B00KBH5O8K/ref=sr_1_1?ie=UTF8&qid=1419883261&sr=8-1&keywords=darwin%27s+theorem http://www.amazon.com/Darwins-Theorem-TJ-Radcliffe-ebook/dp/...
dataphile 12y ago
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.
- japhyr 12y ago
  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.
lmm 12y ago
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.
portman 12y ago
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 http://www.amazon.com/dp/0670025852
graycat 12y ago
<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>
normloman 12y ago
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.
fallat 12y ago
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
dreamdu5t 12y ago
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.
jmnicholson 12y ago
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-truth-complicated-by-the-pursuit-of-mortgages https://thewinnower.com/papers/science-the-pursuit-of-the-tr... 6) https://thewinnower.com/papers/making-scientific-blogging-count https://thewinnower.com/papers/making-scientific-blogging-co...
TylerH 12y ago
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"
adrianh 12y ago
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. :)
volune 12y ago
they should do it all. there is nothing they should not do.
tooatui 12y ago
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.
karlbeecher 12y ago
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/ http://browndogsandbarbers.com/
amelius 12y ago
> 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.
- superuser2 12y ago
  >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.
- ghaff 12y ago
  >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.
- philwelch 12y ago
  > 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.
mschip 12y ago
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.
- munificent 12y ago
  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.
kevinmireles 12y ago
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 :)
vayarajesh 12y ago
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
mastazi 12y ago
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.
MichaelCrawford 12y ago
Come to http://www.kuro5hin.org/ 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.
stevebmark 12y ago
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!
singingfish 12y ago
"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)
vorg 12y ago
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.
iulzz 12y ago
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?
neltnerb 12y ago
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.
Scogle 12y ago
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.
luhgor 12y ago
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 https://www.youtube.com/watch?v=9LfmrkyP81M
scelerat 12y ago
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.
xasos 12y ago
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.
anuragajmera12 12y ago
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
saddington 12y ago
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/ http://john.do/today/ And, here's my thoughts on the importance of a Developer's Blog: http://blog.desk.pm/dev-blog/ http://blog.desk.pm/dev-blog/
DoktorThomas 12y ago
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....
DoktorThomas 12y ago
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....
nonsoike 12y ago
A good resource: https://class.stanford.edu/courses/Medicine/Sci-Write/Fall2014/about https://class.stanford.edu/courses/Medicine/Sci-Write/Fall20...
trx 12y ago
I'm an English kid but I'm a Computer Science major, to. This is why I think I'm on the wrong path.
ckoerner 12y ago
"Even if a project doesn’t require communication" Every project requires communication.
Dreckcath 12y ago
Sure writers can write, they just dont write codes... Dont think its fair to expect them to and vice versa.

318 points by shbhrsaha 12y ago

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

rdrey 12y ago
I think starting with a private blog is great advice, since it removes all apprehensions except for the "too little time" argument.
- henrik_w 12y ago
  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).
ionforce 12y ago
> 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?
- edpichler 12y ago
  Brazil.
sophacles 12y ago
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.
- edpichler 12y ago
  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.
  - sophacles 12y ago
    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.
IndianAstronaut 12y ago
As someone trying to learn Portuguese, I should probably start writing in Portuguese.
bdotdub 12y ago
Have you seen http://750words.com/ 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
- edpichler 12y ago
  Oh, very cool. Thanks, I just bookmarked it here.
Reef 12y ago
http://xkcd.com/1179/ http://xkcd.com/1179/ please :)

kalid 12y ago

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.

debaserab2 12y ago
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.
- therealdrag0 12y ago
  Exactly. Writing helps an idea develop and sometimes change and move in ways we wouldn't have expected.
ivan_ah 12y ago
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/ http://longnow.org/essays/richard-feynman-connection-machine...
- azeirah 12y ago
  That's an absolutely excellent story. I can recommend it to anyone on this site.
  - sophacles 12y ago
    There have been some good discussions around that story here a few times when it was posted.

henrik_w 12y ago

I like this quote (from Joan Didion): "I don't know what I think until I try to write it down."

tjradcliffe 12y ago
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.

euphemize 12y ago

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.

trentmb 12y ago
> combining similar ideas ideas I can't decide if that was deliberate or not.
FigBug 12y ago
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.
seanmcdirmid 12y ago
> 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.

Kalium 12y ago

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.

al2o3cr 12y ago
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`.
azdle 12y ago
> 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.
aswanson 12y ago
"Code that is unreadable by other engineers, even if it's functional, is bad code."
- Retra 12y ago
  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?
robbrown451 12y ago
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.

tomphoolery 12y ago

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.

_neil 12y ago
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 http://www.nostarch.com/hemingwayjs
ivan_ah 12y ago
> 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. ]

azdle 12y ago

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/ http://exosite.com/real-time-device-communication-part-1/

jobu 12y ago

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.

coolsunglasses 12y ago
How did they go about incentivizing tech talks? Have you written anywhere about the things this company did?
- jobu 12y ago
  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.)

Bahamut 12y ago

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.

ggambetta 12y ago

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 http://www.amazon.com/dp/B00QPBYGFI [2] http://www.advancedfictionwriting.com/articles/snowflake-method/ http://www.advancedfictionwriting.com/articles/snowflake-met...

shbhrsaha 12y ago
Great point! Completely overlooked that aspect.
presidentender 12y ago
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?
- ggambetta 12y ago
  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 :)
tjradcliffe 12y ago

k__ 12y ago

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

Retra 12y ago
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.
k__ 12y ago
Funny thing is, I got this you're A or B impression still. Developers and designers, tech and sales, front- and backend...

pluc 12y ago

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-looking-_b_4829981.html 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.

collyw 12y ago
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.

marktangotango 12y ago

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

las_cases 12y ago
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.
- eropple 12y ago
  > 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.
- gaius 12y ago
  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.
  - lmm 12y ago
    Variable and method names can do that, and are more likely to be kept up to date than comments.
- VLM 12y ago
  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.

mathattack 12y ago

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.

emcarey 12y ago

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!

friendcode 12y ago

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

mkramlich 12y ago

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.

joeblau 12y ago

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/ https://blog.joeblau.com/ [2] - https://github.com/joeblau/gitignore.io https://github.com/joeblau/gitignore.io

mirkoadari 12y ago
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!
- joeblau 12y ago
  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.
k-mcgrady 12y ago
>> "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.
- joeblau 12y ago
  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-steve-jobs/?ex=1358226000&en=dc35254b0fcd5490&ei=5090&partner=rssuserland&emc=rss&_r=0 http://bits.blogs.nytimes.com/2008/01/15/the-passion-of-stev...

searine 12y ago

What a circlejerk.

henryw 12y ago

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

LVB 12y ago
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.

harshbhasin 12y ago

I just published my first kindle short story: http://www.amazon.com/dp/B00RA3UD20 http://www.amazon.com/dp/B00RA3UD20 Also, related link on writing: https://news.ycombinator.com/item?id=8793024 https://news.ycombinator.com/item?id=8793024

sigil 12y ago

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.

exacube 12y ago

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

deleted 12y ago

[deleted]

alexggordon 12y ago

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.

deleted 12y ago

[deleted]

VLM 12y ago

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

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

0xdeadbeefbabe 12y ago

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.

tjradcliffe 12y ago
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/B00KBH5O8K/ref=sr_1_1?ie=UTF8&qid=1419883261&sr=8-1&keywords=darwin%27s+theorem http://www.amazon.com/Darwins-Theorem-TJ-Radcliffe-ebook/dp/...

dataphile 12y ago

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.

japhyr 12y ago
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.

lmm 12y ago

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.

portman 12y ago

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 http://www.amazon.com/dp/0670025852

graycat 12y ago

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

normloman 12y ago

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.

fallat 12y ago

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

dreamdu5t 12y ago

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.

jmnicholson 12y ago

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-truth-complicated-by-the-pursuit-of-mortgages https://thewinnower.com/papers/science-the-pursuit-of-the-tr... 6) https://thewinnower.com/papers/making-scientific-blogging-count https://thewinnower.com/papers/making-scientific-blogging-co...

TylerH 12y ago

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"

adrianh 12y ago

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

volune 12y ago

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

tooatui 12y ago

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.

karlbeecher 12y ago

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/ http://browndogsandbarbers.com/

amelius 12y ago

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

superuser2 12y ago
>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.
ghaff 12y ago
>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.
philwelch 12y ago
> 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.

mschip 12y ago

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.

munificent 12y ago
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.

kevinmireles 12y ago

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

vayarajesh 12y ago

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

mastazi 12y ago

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.

MichaelCrawford 12y ago

Come to http://www.kuro5hin.org/ 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.

stevebmark 12y ago

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!

singingfish 12y ago

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

vorg 12y ago

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.

iulzz 12y ago

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?

neltnerb 12y ago

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.

Scogle 12y ago

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.

luhgor 12y ago

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 https://www.youtube.com/watch?v=9LfmrkyP81M

scelerat 12y ago

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.

xasos 12y ago

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.

anuragajmera12 12y ago

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

saddington 12y ago

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/ http://john.do/today/ And, here's my thoughts on the importance of a Developer's Blog: http://blog.desk.pm/dev-blog/ http://blog.desk.pm/dev-blog/

DoktorThomas 12y ago

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

DoktorThomas 12y ago

nonsoike 12y ago

A good resource: https://class.stanford.edu/courses/Medicine/Sci-Write/Fall2014/about https://class.stanford.edu/courses/Medicine/Sci-Write/Fall20...

trx 12y ago

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

ckoerner 12y ago

"Even if a project doesn’t require communication" Every project requires communication.

Dreckcath 12y ago

Sure writers can write, they just dont write codes... Dont think its fair to expect them to and vice versa.