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.
Software engineers should write
101–110 of 166 posts
Re: Software engineers should write
#102Hey 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
I agree. Funny how people worry about documentation going out of date, but not code going out of date.
I guess it is more acceptable to have a bug in the code than a mistake in the documentation.
Re: Software engineers should write
#103Hey 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
I agree. Funny how people worry about documentation going out of date, but not code going out of date. I guess it is more acceptable to have a bug in the code than a mistake in the documentation.
Exactly the opposite. The documentation gets out of date because people update the code without updating the documentation.
Re: Software engineers should write
#104Great article. As somebody who has always identified with the "math" kid, I've never dreaded nor disliked writing. In fact, I often have the urge to write. My biggest issue is confidence in my vocabulary. After years of schooling for engineering I feel as though my non-technical vocabulary hasn't progressed much since high school and always seems to fall to the bottom of my personal studies.
I believe vocabulary is one of the least important facets of writing. Prose is combinatorial. Even with a smattering of words, there are a near-infinite number of novel, expressive ways they can be combined.
It's rare that a great concept can't be expressed from the lack of a word or two. You almost always need full phrases and sentences to get an idea across anyway.
Also, vocabulary is one of the things most amenable to being improved during editors. I've heard of lots of famous others whose first drafts have "" 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.
Re: Software engineers should write
#105I was always an "English kid", came close to failing my math subjects in middle school and finally in high school, I did fail Algebra I, and had to re-take it the next year. Meanwhile, I was in advanced programming courses and on my way to take an AP Computer Science course in the last semester of my sophomore year. Looking back, that experience taught me about how important modeling is to pedagogy. The fact is, my A…
I always felt like school-level English classes were very hazy, muddy environments where you didn't need to have clear thinking and the structures (the English language mainly) didn't strictly follow any internal logic, opposite math. Peers got good marks for presenting half-baked ideas in inarticulate, thesaurus-abused essays, as long as they made sure to repeat their limp argument, cut up into a specified number of points, in the extremely redundant structure imposed by the curriculum (say what you're going to say, say it, then say what you said, with different synonyms each time) and use different joining-words or whatever term they used for obnoxiously putting "also" "further" etc. at the start of every new paragraph. Intellectual laziness was rewarded by the system, purposefully or not.
Those classes probably turned off a sad number of would-be good writers from learning how to write creatively, efficiently, or even reasonably. I had exactly one English teacher who was reasonable and only taught to these abominable standards as required by the state but let real writing be rewarded in other assignments; he understood the reality of the language and that the point of your writing should be moreso effectively articulating ideas, effecting desired emotional responses, or provoking thoughts rather than some nonsense a committee at the Department of Education decided is proper and that legions of English teachers across the country take to heart as dogma and revel in the sadism of. Otherwise, throughout the years it was splitting hairs over prescriptivist grammatical minutiae, the aforementioned ridiculous essay structure, memorizing obsolete Shakespearen-era "vocabulary words" that no writer writing for a living audience would even consider using, and going on about how any grammatical structure or word that appeared after 1900 is objectively wrong.
I could have put much less effort into them than I did and still gotten As but I preferred to use them as an exercise in trying to work good writing around the myriad deeply-rooted problems in how I was forced to present it. That's the only bonus point I can give to it as a learning environment.
English classes in college have just been the same disappointment with a different mask on for the most part, except for exposure to real research methods, but still lag behind the real world in forcing you to use non-internet sources.
Was the experience different for you?
Re: Software engineers should write
#106> 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 al…
> The problem with writing is that you usually do it by serializing your thoughts in one go. Programming on the other hand is an activity where you almost randomly jump from one point to the other.
It's startling how much I write the exact same way I code, namely by jumping around from place to place. It's more important that your written thoughts deserialize linearly than it is for you to serialize them that way.
Re: Software engineers should write
#107I 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 d…
>> "Even though Steve Jobs said people don't read" Source on this? As a general statement that sounds kind of ridiculous. I would have thought people are reading more than ever considering how much of the internet is text. Also a little strange considering Apple runs a bookstore.
It was from the New York Times [1] they asked Steve about the Kindle reader.
> “It doesn’t matter how good or bad the product is, the fact is that people don’t read anymore,” he said. “Forty percent of the people in the U.S. read one book or less last year. The whole conception is flawed at the top because people don’t read anymore.”
[1] - http://bits.blogs.nytimes.com/2008/01/15/the-passion-of-stev...
Re: Software engineers should write
#108I 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 d…
Wow, gitignore is an OSS project?! Didn't know this. Are you looking for collaborators? Love your project and have been looking for something to tinker with on free time. Kudos for great work!
The gitignore.io site is OSS as well as the gitignore template list maintained by GitHub. If you want to collaborate that would be cool, although there isn't much the site does :). All I've been doing recently is merging pull requests and updating submodule.
Re: Software engineers should write
#109There 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…
How did they go about incentivizing tech talks? Have you written anywhere about the things this company did?
The TechTalks had a few purposes. First, it was to spread knowledge within the company about what other groups were working on and how they were doing it. Second, it was for recruiting new developers. (If the talk went well internally, then we were often asked to do it again for local developer groups or meetups at area colleges.) Third, it was part of the career development they tried to do - trying to create good Architects that knew the business and the problems that needed to be solved.
The talks were incentivized as part of the bonus structure. If the company did well, and you completed your goals, then you could get up to X% of your salary as a bonus. (Also, they usually included free lunch)
The technology and the people at that company were really great to work with - I probably got more experience in one year there than five years at any other company. Unfortunately it was in the advertising business, so many of the business practices were slimy and cutthroat. (It seemed like every month we had a crisis where either Google, Microsoft, or Apple didn't like what we were doing and wanted to shut it down.)
Re: Software engineers should write
#110I like this quote (from Joan Didion): "I don't know what I think until I try to write it down."
There's a similar one from Churchill when asked by a frustrated colleague to get to the point: "How can I know what I think until I hear what I say?"
I think a lot of writers are like this: we are painfully aware of our ignorance, our uncertainty, our lack of belief. The struggle to articulate our beliefs is a struggle to form them. Non-writers often seem to "just know" what they think, which is to me quite remarkable. But they also frequently lack the tools to analyze their beliefs and how they are constructed, because they never have to go through the slow and painful process of figuring them out.