nwhittier

I have substantial concerns about the lacking software design/development skills in most crops of CS graduates. These concerns are founded predominantly in hiring and training CS grads over several years in a budding startup. Many say that CS is not about software design/development, and while that may be true, I think it's a problem.

I think that one of the possible solutions for this problem is to integrate open source participation in the standard CS curriculum. However, I am struck by your question, as I had never considered the possibility of an 'art' of software design. Upon reflection, it makes perfect sense, and (not to diminish the point or question) seems almost obvious.

i just wanted to highlight the importance of your question, and thank you for the insight regarding software development as a strange hybrid between science and art.

To attempt a non-answer to your question: I don't think it can be taught exclusively as either, rather it is some combination thereof.

This makes great points regarding how easy it is to overlook simple steps.

I got a good feel for this when participating in QA, where missing any step results in a "Resolved: Cannot reproduce" update, and scorn from the developer(s). After careful review, you realize that between step 3 and 4, there should have been a note about using the Enter key instead of clicking the Login button (or some other variable action).

The key in QA is to make sure that a computer could replicate the issue following your steps (computers being much more literal than your spouse, child, cousin, non-technical relative, etc.). I always document bugs assuming that a computer will be trying to replicate the issue. That means consistency in object/detail reference, verbs, quotation, case, etc. Just like in a recipe, where someone may get confused or start second-guessing themselves if you switch from "tsp." to "teaspoon" repeatedly.

There is a little bit of room in end user documentation, as placeholders will often offer comfort to users. That is, merely identifying that a section is missing, or more details are needed in your docs, can make a huge difference. It is the difference between someone getting lost and giving up, and that same person realizing that they are lost in an area that is declared as confusing. This simple acknowledgment could lead to a user investigating further (or even contacting you via email/irc/whatever), instead of just finding a different project.

As alluded by Mel, and several of the comments, the problem is assuming that everyone else carries the same experience/perspective/assumptions that you do. I am guilty of it too, and it is time to stop complaining about writing the documentation. Even though it's a pain, just start updating it so that anyone can understand what you are trying to say. It will save everyone a lot of time in the long run.

And for those of us who want to participate in opensource - find the documentation that's confusing, and contact the project participants about fixing it! Don't give up, or just complain, it's the perfect avenue to start participation, and you get to learn a lot about the project along the way.