
Software engineers should write - shbhrsaha
http://www.shubhro.com/2014/12/27/software-engineers-should-write/
======
edpichler
"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.

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

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

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

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

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

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

~~~
ivan_ah
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
That's an absolutely excellent story. I can recommend it to anyone on this
site.

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

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

~~~
ivan_ah
> _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. ]

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

~~~
ivan_ah
> _a comical idea to try to market a book toward students these days_

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

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

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

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

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

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

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

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

To take a trivial example:

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

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

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

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

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

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

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

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

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

~~~
k-mcgrady
>> "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
It was from the New York Times [1] they asked Steve about the Kindle reader.

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

[1] - [http://bits.blogs.nytimes.com/2008/01/15/the-passion-of-
stev...](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)

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

------
ggambetta
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-
met...](http://www.advancedfictionwriting.com/articles/snowflake-method/)

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

------
henryw
I've always admired the writing style in the Economist:
[http://www.economist.com/styleguide/introduction](http://www.economist.com/styleguide/introduction)

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

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

------
0xdeadbeefbabe
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
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/...](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)

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

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

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

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

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

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

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

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

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

------
pluc
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-...](http://www.huffingtonpost.com/chris-parnin/scientists-begin-
looking-_b_4829981.html)

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

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

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

------
jobu
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
How did they go about incentivizing tech talks?

Have you written anywhere about the things this company did?

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

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

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

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

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

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

------
azdle
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/)

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

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

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

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

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

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

------
henrik_w
I like this quote (from Joan Didion):

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

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

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

------
karlbeecher
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/)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

------
saddington
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/)

------
friendcode
For all the software engineers who want to write:
[https://www.gitbook.com](https://www.gitbook.com)

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

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

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

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

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

------
nonsoike
A good resource: [https://class.stanford.edu/courses/Medicine/Sci-
Write/Fall20...](https://class.stanford.edu/courses/Medicine/Sci-
Write/Fall2014/about)

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

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

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

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

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

------
trx
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
"Even if a project doesn’t require communication"

Every project requires communication.

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

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

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

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

------
dreamdu5t
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
Software engineers should write at thewinnower.com. Here's why:

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

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

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

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

5) [https://thewinnower.com/papers/science-the-pursuit-of-the-
tr...](https://thewinnower.com/papers/science-the-pursuit-of-the-truth-
complicated-by-the-pursuit-of-mortgages)

6) [https://thewinnower.com/papers/making-scientific-blogging-
co...](https://thewinnower.com/papers/making-scientific-blogging-count)

