Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Software engineers should write

shubhro.com

Post reply on HN
Print view View original

31–40 of 166 posts

Re: Software engineers should write

#31

Post by rdrey »

edpichler wrote: post #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 thi…

I think starting with a private blog is great advice, since it removes all apprehensions except for the "too little time" argument.

Re: Software engineers should write

#32

Post by debaserab2 »

kalid wrote: post #24

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.

Additionally, I've found that writing out the problem or solution in plain English sometimes helps me make the leap from conceptualizing to actually understanding.

Re: Software engineers should write

#33

Post by las_cases »

marktangotango wrote: post #21

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

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.

Re: Software engineers should write

#34

Post by therealdrag0 »

debaserab2 wrote: post #32
kalid wrote: post #24

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.

Additionally, I've found that writing out the problem or solution in plain English sometimes helps me make the leap from conceptualizing to actually understanding.

Exactly. Writing helps an idea develop and sometimes change and move in ways we wouldn't have expected.

Re: Software engineers should write

#35

Post by henrik_w »

rdrey wrote: post #31
edpichler wrote: post #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 thi…

I think starting with a private blog is great advice, since it removes all apprehensions except for the "too little time" argument.

On the other hand, having other people read what you have written can be quite a thrill (especially if it becomes popular). Submitting your blog posts to HN and reddit/r/programming also can get you good feedback and alternative views (and, for that matter, mean comments too).

Re: Software engineers should write

#36

Post by eropple »

las_cases wrote: post #33
marktangotango wrote: post #21

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

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.

> How do you feel about the saying that code itself should be as good as documentation?

Not him, but I'll take a crack at it: adorable, high-minded, and wrong. Most people are not going to walk through your code to grasp it in its entirety; design, and document, accordingly.

At the very least, you should have exhaustive, well-considered, commented unit and integration tests to demonstrate its use cases and (foreseeable) failure modes.

Re: Software engineers should write

#37

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

Re: Software engineers should write

#38

Post by 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/

[2] - https://github.com/joeblau/gitignore.io

Re: Software engineers should write

#40

Post by gaius »

las_cases wrote: post #33
marktangotango wrote: post #21

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

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.

The code doesn't document your intent. There's no way to tell if something weird is a bug, or a feature for an edge case that was never written down.
Post reply on HN