

The Real Reason Silicon Valley Coders Write Bad Software - dsr12
http://theatlantic.com/national/archive/2012/10/the-real-reason-silicon-valley-coders-write-bad-software/263377

======
zachgalant
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.

------
tomkarlo
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.

------
bjhoops1
"Telling somebody to "look it up in the Wiki" is tantamount to telling them to
go f __* themselves." Ha! So very true.

~~~
dmorgan
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.

------
ikailan
This article is wrong. Here's why: [http://ikaisays.com/2012/10/09/why-the-
real-reason-silicon-v...](http://ikaisays.com/2012/10/09/why-the-real-reason-
silicon-valley-coders-write-bad-software-is-wron/)

