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
Software engineers should write
21–30 of 166 posts
Re: Software engineers should write
#22Where 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.
Re: Software engineers should write
#23"Even if nobody reads your essay, writing it will make an impact on you."
After reading a post in HN (https://news.ycombinator.com/item?id=5614689) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese.
I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thing to do and it is the best subject to improve myself. It's not an easy task, and I do not feel I'm improving yet, but something in me tell me that I should keep doing it.
Re: Software engineers should write
#24I'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.
Re: Software engineers should write
#25I 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.
True enough - but code that humans can't read is far more difficult to debug, to profile, and to optimize. Efficiency can be improved after the code is working, but improving readability on a prematurely-optimized codebase frequently involves `rm -rf`.
Re: Software engineers should write
#26I like this quote (from Joan Didion):
"I don't know what I think until I try to write it down."
Re: Software engineers should write
#27I find myself uncertain about the thesis. Code that is clear and expressive to a human should not be assumed to also be efficient and optimal for a computer. As writers say, know your audience.
"Code that is unreadable by other engineers, even if it's functional, is bad code."
Code is designed to solve problems. If someone can't read your code, they are going to have a hard time using it to solve their problems. If you don't document edge cases, modes of failure, intent and methodology... then it is worse code than it could be. Somebody won't be able to use it because they won't be able to tell if it solves their problem.
A few weeks ago I read a quote about someone saying that good code should be 'self-documenting' and that it should be obvious what it does. This is a red herring -- it assumes you wrote code that works perfectly. If there is a bug in your 'self-documenting' code, then how is someone supposed to know if it is wrong or not?
Re: Software engineers should write
#28When 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!
Re: Software engineers should write
#29For all the software engineers who want to write: https://www.gitbook.com
Re: Software engineers should write
#30Why 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…
The pistol on your novel's cover is a CZ-75. It's not an unknown gun by any means, but it's relatively uncommon in real life; sushi to the hamburger that is a Glock or a Beretta. Despite this, it's a common choice for infographics where just "a gun" is needed, and I can't for the life of me figure out why. I'm curious - do you know why that particular pistol was chosen for your cover?
Interesting, never thought of figuring out the model!
The cover was made by a freelancer I found on 99designs.com (I'm really happy about that experience, BTW - and I have nothing to do with them, I just liked the service). The pistol looks good and the image was royalty-free, which is probably why the freelancer chose it.
But in retrospect you're right, I should have checked. The only pistol specifically mentioned in the novel is a "H&K" (not even the model), but there are many other anonymous ones. This CZ-75 could be one of these :)