News for hackers. Stuff that matters.
Re:The Real Reason Silicon Valley Coders Write Bad Software by zachgalant on Tuesday October 09, 2012 @03:38PM (#4633539)
Totally agree. When people learn to code, it's important to teach them that code is written for other humans to read and understand.

I'm making CodeHS (http://codehs.com) to teach beginners to code and stress coding style and code readability.

We give every students real live tutors who help them out and critique their code to improve their understanding.

Re:The Real Reason Silicon Valley Coders Write Bad Software by tomkarlo on Tuesday October 09, 2012 @06:43PM (#4634298)
Engineers are hired, and paid, to code and write new functionality. It's unsurprising that they're generally not going to prioritize the quality of documentation, since that effort primarily benefits someone OTHER than the author.

While it's great to encourage better composition by the developers, companies should also consider the benefits of hiring proper technical writers - people who work primarily to improve and refine the quality of internal and external communications.

There's an added benefit: sometimes it's harder to write documents for people unfamiliar with a subject when you yourself are very deeply immersed in it. (E.g. an API is written a certain way BECAUSE that made sense to the guy who designed it. He's not going to see what has to be explained to a third party, because he sees it as intuitive.) Having a technical writer provide a more detached perspective on the quality of a document can be invaluable for both the developer and the final reader.

Re:The Real Reason Silicon Valley Coders Write Bad Software by bjhoops1 on Tuesday October 09, 2012 @03:48PM (#4633577)
"Telling somebody to "look it up in the Wiki" is tantamount to telling them to go f* themselves." Ha! So very true.
Re:The Real Reason Silicon Valley Coders Write Bad Software by dmorgan on Wednesday October 10, 2012 @05:00AM (#4635599)
True.

Putting up a Wiki as documentation for a project/API, essentially means "we don't have time to write documentation, so we jotted together some napkin notes, maybe you can come in and fix them".

I've never seen "wiki for documentation" work in practice. It's always left in some semi-incoherent state, stale and incomplete.

Re:The Real Reason Silicon Valley Coders Write Bad Software by ikailan on Wednesday October 10, 2012 @03:16AM (#4635397)