Software engineers should write
shubhro.com
shubhro.com
After reading a post in HN (https://news.ycombinator.com/item?id=5614689) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese.
I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thing to do and it is the best subject to improve myself. It's not an easy task, and I do not feel I'm improving yet, but something in me tell me that I should keep doing it.
"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?
First: you've overcome a big hurdle in learning a second language, I understood what you are trying to communicate, and I did so on my first reading of it. To me, this means you're already good at english! (By comparison if I tried in my second language, which is German, I would need a few drafts and a proof-reader).
Second: You're doing commas better than a lot of native english speakers. That's pretty impressive.
Third: There are a couple of grammatical/phrasing errors I'll tell you about in your comment. These are really common errors amongst people who learn English as a second (or Nth) language, and I'm not doing it to belittle you, but to help your stated goal of improvement.
I'm doing it since 09/22/2014
This is one of those wierd places in English where the verbs "to do" or "to be" combine strangely with tenses and idioms. I'm not so sure of the technical way of stating the problem, but here's a couple of examples of a more natural way to state it:
* I've been doing it since 09/22/2014.
* I've done it since 09/22/2014.
but something in me tell me that
This is a small one, and maybe a typo, but it is part of a pattern I've seen a lot. Again, not great at the technical grammar terms, but it should be:
* but something in me tells me that
(notice the 's' on tells).
Anyway I'm always impressed with people who can learn a second language well, and wanted to encourage it and help if can.
I 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.
Invariably, that outlook is expressed by people who happen to only speak one language.
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.
Try "considered" or "thought about".
"Cogitated" is very similar with the Portuguese translation "Cogitado", broadly used. And on Google Translate it appears as the first option.
I think that literature and travel are the keys to improve on this.
Any native English speaker who goes online has to be used to English being used very poorly by now, and it is much less annoying when the person making mistakes is a non-native speaker trying to learn rather than a native speaker who is lazy or functionally illiterate.
Everything you've written is completely understandable and most of it is arguably grammatically okay though sometimes phrased in ways that sound unnatural in colloquial English. For example "sometimes I do some mistakes" would be better said "sometimes I make mistakes", though the way you phrased it is perfectly understandable.
I also sell some simple software overseas and, for doing business, if you have a bad grammar or a poor vocabulary, you loose points in the price negotiation. The other part can feel like they are negotiating with a hick.
Furthermore, everything you write on web will be technically forever, you need to delight the readers and poor English can annoy them, as I've already commented.
http://www.merriam-webster.com/dictionary/loose http://www.merriam-webster.com/dictionary/lose
This is a common error for the natives as well so don't feel bad about it.
[Edit: I a word]
If the screw is too loose it could fall off and you might lose it.
The two points that the previous poster highlighted: while perhaps the native-fluent speaker will notice that the phrases have a non-standard form, both sentences are completely intelligible.
Living abroad from the United States has only served to stretch my conception of "proper English" even further.
This really makes me happy. I never left the country, and my first international travel will be to Melbourne in February/2015 where I will can test myself.
I think the reason why he used commas well (And that many other portuguese speakers use commas better than native english speakers) is that in portuguese you NEED to.
If you don't use commas properly in portuguese, you text can easily get excessively ambiguous, because of that schools here stress the comma a lot, I for example had in my fourth grade entire weeks dedicated to commas, and forgetting commas, even in non-langauge tests (example, in math tests) frequently resulted in some punishment (in math tests forgetting commas resulted into a loss of 0.1 points in the grade for each comma, out of the maximum of 10, thus if your math was correct enough to score 5, but you forgot 5 commas, you would instead score 4.5)
http://en.wikipedia.org/wiki/Uses_of_English_verb_forms#Prog...
The first bullet is an example of past perfect progressive, which combines the past tense with the perfect and progressive aspects -- in other words, it describes that specific part of an ongoing action (progressive aspect) which has already been (past tense) completed (perfect aspect).
The second bullet exemplifies the past perfect, describing an action which has already been completed, without the additional progressive aspect to signify that the action is ongoing.
Both are correct, and would likely be understood to mean the same in colloquial usage; the only difference is that the former is somewhat more specific than the latter, in stating that the action is ongoing rather than leaving that to be inferred.
http://en.wikipedia.org/wiki/English_verbs#Third_person_sing...
This is a slightly unusual case in English, in that otherwise regular verbs almost always take a trailing (e)s in their third-person singular present-tense form. For example, conjugating to tell in the present tense:
1st person: I tell; we tell 2nd person: you tell; you tell 3rd person: he tells; they tell
Presumably this exception exists for historical reasons; why we keep it around, save habit, I have no idea. In any case, we do it with more or less all English verbs, save a few:
http://en.wikipedia.org/wiki/English_irregular_verbs#Verbs_w...
> > 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,
Writing about a topic is a good test of whether you can explain it simply.
via http://longnow.org/essays/richard-feynman-connection-machine...
I have been endeavoring to get in the habit of writing about things that I learn. My main obstacle is the feeling that, even if I can write and explain the topic well, other people can too and already have; so why bother writing about it? But that misses the point -- or even two points.
The writing helps me; the fact that someone else wrote is irrelevant. Further, my writing, even if the subject matter is hardly original, might in fact help someone else: not everyone favors the same calculus textbook, or the same Python programming manual, or the same history of World War II. People enjoy different writing styles, different perspectives, even different fonts and page layouts. (I've elected against buying at least one book because I found the page layout excessively annoying to look at!)
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.
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. ]
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.
I did very well at English at school, but failed hard at maths whilst freelancing from home after teaching myself PHP.
I really wish I'd engaged (and was taught) maths in the same way as I did with code - I remember feeling quite annoyed at the way I was being taught maths which was basically "when you see a question asked in this way, you answer it by following these steps". I think if I'd been taught maths through experimentation and having "projects" to solve in the same way I learned to code, I would've been quite a good maths student.
Those classes probably turned off a sad number of would-be good writers from learning how to write creatively, efficiently, or even reasonably. I had exactly one English teacher who was reasonable and only taught to these abominable standards as required by the state but let real writing be rewarded in other assignments; he understood the reality of the language and that the point of your writing should be moreso effectively articulating ideas, effecting desired emotional responses, or provoking thoughts rather than some nonsense a committee at the Department of Education decided is proper and that legions of English teachers across the country take to heart as dogma and revel in the sadism of. Otherwise, throughout the years it was splitting hairs over prescriptivist grammatical minutiae, the aforementioned ridiculous essay structure, memorizing obsolete Shakespearen-era "vocabulary words" that no writer writing for a living audience would even consider using, and going on about how any grammatical structure or word that appeared after 1900 is objectively wrong.
I could have put much less effort into them than I did and still gotten As but I preferred to use them as an exercise in trying to work good writing around the myriad deeply-rooted problems in how I was forced to present it. That's the only bonus point I can give to it as a learning environment.
English classes in college have just been the same disappointment with a different mask on for the most part, except for exposure to real research methods, but still lag behind the real world in forcing you to use non-internet sources.
Was the experience different for you?
I also disliked the emphasis on literary analysis. It so often seemed like contrived flimflammery crossed with psychoanalytic mumbo-jumbo. If tvtropes (or allthetropes) had existed back then, I think I would have performed much better on my English homework. After all, those sites do include the Jungian archetypes and the basic plots as a subset.
As it is, my high school English classes drove me far away from anything even remotely similar until a lifetime of reading fiction, a shameful amount of blathering on Internet message boards, and the exhortations of the "National Novel-Writing Month (NaNoWriMo)" organization convinced me to try to write a novel in November of 2012. Two years later, I have written 500 kb, with maybe 130 kb left to go before I snap it off and start the next one. Then there's also the matter of the default HTML stylesheet, continuity notes and timelines, the character, vehicle, location, and artifact indices, working hyperlinks, and testing the release version on all available e-reader programs and devices.
As for my old English teachers, I bite my thumb at them, like Sampson. I give them the fig, like Vanni Fucci. And just as golf is a good walk, spoiled, English class is a good read, ruined. Even with those ancient cultural references rattling around my bonebox, I find that an increasingly large fraction of my memes are drawn from television, film, music, video games, and popular web sites, and a vanishingly small portion from the old literary canon.
That's how I know that the Belmonts love Devo. If you understand why, you probably won't need to thank an English teacher.
All I really ever needed was a pile of books that I enjoyed reading and a copy of Strunk and White (minus the part about always putting sentence punctuation inside the quotes, because that's just madness). What I got was about 10 years of pedagogical torture that discouraged me from trying something that turned out to be a fun hobby.
> 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.
I can't decide if that was deliberate or not.
I'd do it again, and I recommend anybody that gets the change to do it as well.
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.
I got the important takeaway from that experience, but many people do not, and it is a shame.
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.
/rant
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.
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.
The truth is, 95% of developers do not write readable code. But I've been doing this for a while, so I can follow pretty much anything. It's the shear volume of legacy code in the typical code base thats the problem.
What kills me is dead code that you don't know is dead; hundreds of class files, dto's, booleans passed around to control processing that are always false now, because that alternate path is no longer used. And protocol messages, oh god the hundreds of protocol messages, but we only use 10 now.
Edit; I've been the hero more than once documenting stuff like the above.
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.
A further advantage: such comments have longer halflives. A rewritten method may still have the same purpose long after all details are changed.
I would go for the function, and pass along Knuth's advice about premature optimization. If you're writing at such a low level that function calls actually aren't acceptable, go with a comment "// renormalize vector." Your instinct should be the function though. I bet there is more than one vector normalization going on in this hypothetical codebase, and that line looks pretty typo-prone.
I guess it is more acceptable to have a bug in the code than a mistake in the documentation.
Source on this? As a general statement that sounds kind of ridiculous. I would have thought people are reading more than ever considering how much of the internet is text. Also a little strange considering Apple runs a bookstore.
> “It 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...
As a hobby I've done a lot of reading around this; I've written three feature-length screenplays, and a novel you can find in Amazon[1], using very structure-centric approaches (as a result, my characters tend to be too flat).
Take a look at The Snowflake Method[2], unsurprisingly designed by a novelist who is also a theoretical physicist. Even with The Hero's Journey, there's a surprising amount of well-understood structure behind every story.
[1] http://www.amazon.com/dp/B00QPBYGFI [2] http://www.advancedfictionwriting.com/articles/snowflake-met...
I'm curious - do you know why that particular pistol was chosen for your cover?
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 :)
Screenplay structure is so tight and formal it's almost like poetry, an analogy I found very useful.
My novel (http://www.amazon.com/Darwins-Theorem-TJ-Radcliffe-ebook/dp/...) was developed much more organically.
I'm an experimental physicist, and the process for me was more like setting up an experiment, from early ideas to failed prototypes to little side explorations to a final result with (hopefully) all the loose ends tied neatly away where the reader can't see what went into the making.
I found Stephen King's book on writing to be one of the best for understanding the organic process of creating stories. If you haven't read it, I'd strongly recommend it: http://www.amazon.com/Writing-Stephen-King-ebook/dp/B000FC0S...
I agree with what you're saying... a novel is the end product, a screenplay is a blueprint. It took me 4 years to write the novel (admittedly very on and off) and ~3 months to write each of the screenplays. Hopefully my next novel will be faster.
What was your experience of writing both formats in terms of time and effort?
My novel took 5+ years of blood, sweat and re-writes.
Writing a passable screenplay took five days, about six hours a day (evenings 6 - midnight). I don't expect I'll ever sell it, but I'm as certain as anything that it's better than a lot of screenplays that have been sold.
I'm mostly a poet, and love structure. Once I understood the structure of a screenplay, it just happened. Novels in contrast are these huge unstructured messy awkward wobbling teenage flailing morasses. The lack of structure, the lack of constraint, the lack of form is something I struggled with for a long time, and while I expect my next effort won't be quite as painful, I don't ever expect it to be easy.
"Form is liberating", as the engineer's proverb goes. Novels don't have it, and are therefore much more work.
Like you, I'm fascinated by story structure, the hero's journey, and the mono-myth. And I've struggled with creating something less than flat characters.
I've read the Snowflake method, and parts of it definitely work for me. Another book that I highly value is Dwight Swain's Technique's of the Selling Writing. This was one of the first books that I read on writing fiction, and I still think it's one of the best. I would also recommend Baboulene's, The Story Book, for it's discussion on subtext.
Unfortunately for me, the focus on technique left me not only with flat characters but also a severe case of writer's block. However, I may have found a solution to both problems in John Dufresne's Is Life Like This? Dufresne advocates a more organic, even serendipitous, approach to story creation. For him at least, the results can be wonderful (read his Love Warps the Mind a Little, or his short stories in Johnny Too Bad), and for me, it's got me writing (finally!) and seeing my characters as something more than just cardboard cutouts. Like anything else, it's not for everybody, and YMMV.
Good luck, and keep writing!
The first book I've read that really resonated with me about giving life to characters is The Screenwriter's Bible by David Trottier. BTW, I've read a lot more books about screenwriting than about writing novels, but I believe both apply... stories are stories.
I think he might mean that writing for human consumption can be harder than most people think.
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/...
For a short story writer the primary challenge is to introduce your characters, their problem and their actions in as few words as possible. Short fiction is focused. You've got one or two main characters who have one problem.
Novels sprawl. They have many characters, many problems, and are typically spread over a much large time-scale. There are novels that aren't much more than "longer short stories" but they tend to be pretty thin stuff.
So for a short story writer the problem is cutting out anything that is not absolutely necessary to the finished whole. For a novelist the problem is keeping in control of the huge unwieldy structure, because it's just really difficult to hold it all in your head at once.
Software analogy: micro-controller development vs desktop application development. For the first you're mostly worried about resource usage. For the second you're mostly worried about it turning into an e-mail client, operating system, or EMACS over the course of development.
I had written and published a very small number of short stories before writing a novel, but didn't really study them until after. One of the great things about short stories, it turns out, is that there's so little money in them that there are classes taught by really good authors very cheaply, at least in Canada (for anyone in Vancouver I highly recommend Caroline Adderson's weirdly-named but absolutely excellent course "Fiction Series for the Weekend Student" from SFU, which fundamentally focuses on short story structure: http://www.sfu.ca/continuing-studies/courses/cpw/fiction-ser...)
I did write a couple of throw-away novels before writing "Darwin's Theorem", and while that process was useful, it didn't really prepare me for the real thing, which involves far more re-writing than anything else (at least the way I do it.) A book you're writing for practice can have all kinds of flaws... a book you're writing to publish has to be as perfect as you can make it (think of it as the difference between a weekend project for your own amusement vs code you're going to ship.)
From http://www.huffingtonpost.com/chris-parnin/scientists-begin-...
> Scientists are finding that there may be a deeper connection between programming languages and other languages then previously thought. Brain-imaging techniques, such as fMRI allow scientists to compare and contrast different cognitive tasks by analyzing differences in brain locations that are activated by the tasks. For people that are fluent in a second language, studies have shown distinct developmental differences in language processing regions of the brain. A new study provides new evidence that programmers are using language regions of the brain when understanding code and found little activation in other regions of the brain devoted to mathematical thinking.
Pinker uses software terms to describe good writing: convert a _web_ of ideas into a _tree_ of syntax into a _string_ of words.
Which in a way helps prove one of the article's points: writing and programming are alike in their need for precision and clarity. :)
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.
Have you written anywhere about the things this company did?
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.)
I agree that writing can be helpful for many things, such as expressing emotion, or telling stories, or just a journal. In those scenarios, it's not dangerous to get it wrong. No one will lose their way in a technical project because you can't write cleanly about your dog.
Write anything except technical articles, until someone comments with something like "this was really well written!" Then you can consider adding to the painful cloud of tech articles.
If you release a tech blog post without editing (and largely re-writing) it a minimum of three times, stop doing it. Seriously. You're not helping.
Also, if you're a newcomer to a tech field and get discouraged by trying to learn about something from online resources, 90% of the time it's not you. It's the author being unable to clearly present ideas. Don't get discouraged!
I'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/
But don't feel you "should". Essays are a bit like code - but if you want to get better at coding, you'll do better practicing coding than practicing essays. Likewise if your goal is "impact"; blog posts, particularly general ones like this, are ten-a-penny - even really good ones. Whereas really good software libraries are rare, even now - and you're more likely to write a specialist software library, with a small audience but one for whom that library is vital, than an equally specialist blog post. And while writing about something may clarify your thoughts, it's nothing next to setting that thing down in code.
Once again, do what you enjoy. If you like to paint, paint; if you like to make music, make music. But if you'd rather just code, or even just watch TV (the very epitome of unproductive wastefulness - but the typical blog probably achieves very little more), that's fine too. Don't let anyone tell you you shouldn't.
I think 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.
Also, related link on writing: https://news.ycombinator.com/item?id=8793024
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>
Should you take it to the extreme Knuth did with Literate Programming? I personally don't. But, once I've successfully explained to the computer what it should do (my program works) I look for ways to better communicate what it's doing (my program is readable). In many cases that's harder than solving the technical problem at hand.
Concision and simplicity seem to be the key to that. I agree with the author that "like good prose, good code is concise," although for prose that's more a matter of taste. Otherwise we'd all be reading a lot more Hemingway.
"I don't know what I think until I try to write it down."
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.
Its emphasis on clarity and concision translates directly to code, both in terms of algorithmic efficiency and human readability, comprehension, maintainability, etc.
Obligatory link: ecc-comp.blogspot.ca
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.
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.
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.
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.
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.
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
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...
Developers and designers, tech and sales, front- and backend...
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.
Now, I just need to learn a programming language and start coding so I can improve my human/computer communication skills :)
If you need some help getting started, try this: http://john.do/today/
And, here's my thoughts on the importance of a Developer's Blog: http://blog.desk.pm/dev-blog/
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
(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)
Maybe software engineers should write less.
As writers say, know your audience.
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.
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?
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.
Every project requires communication.
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.
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.
1) their writings will be preserved with the same power that libraries afford traditional scientific publishing
2) They wont just be blogging, they will be publishing.
3) They can assign a digital object identifier (DOI) at their discretion making their work "count" in the scholarly literature.
4) Their blog will be automatically formatted as a PDF.
5) https://thewinnower.com/papers/science-the-pursuit-of-the-tr...
6) https://thewinnower.com/papers/making-scientific-blogging-co...