Quote:
Originally Posted by HarryT
Absolutely. Each section of the system should be described once and only once. I would still maintain, though, that the ability to write clear and easily-understood English (or whatever language it is you're writing in, of course) is an absolutely essential aspect of the job of a programmer - at least if you want to do well in the customer-facing aspects of the job that are a fundamental part of it for anyone working in a commercial environment. You're not going to be able to win work from customers unless you can present your proposed solution to them well.
|
Writing skills certainly plays a part in many job areas of programming and you may limit your career paths in some areas if you can't convey ideas in a suitable way. However, that still does not imply that to be a good coder you need to be able to write decent documentation.
I've worked on systems where very little documentation was required through to those where complete formal methods were applied and forests probably laid waste to cover the amount of paper generated when the client printed it all out. In some cases ability to clearly convey ideas in written form was crucial, in others the client was only interested in the prototype/mock up of an app.
I do think been able to convey ideas is important for programmers, especially those who work in a team which makes up the majority of business coding. However, just because some programmers cannot write good documentation doesn't imply they're bad coders. Just as been able to write good documentation does not make one a good coder.
Ideally you want people good at both, but I would imagine the real reason most documentation is not up to scratch is that management do not want their coders spending time doing something other than coding. Unless one of the selling points of an app is it's API, there's much less incentive to fully document and maintain it.
This can be compounded by major changes been made on a tight deadline with insufficient time allowed to update documentation. Docs then suffer from either been inaccurate or poorly thought out because they've been rushed.
Obviously this differs on the sector we may be talking about. Some areas documentation is crucial and projects won't go ahead without reams of it. For formal systems it's a key part of identifying potential issues. For other sectors it's mainly as api usage documentation for anyone wishing to extend a product or use a library and may get less attention.
Either way, I think it's wrong to conclude that poor documentational skills is why bad code/software is written.