My Pen Is My Tongue

A few days back I sent out a series of tweets about "self-documenting code". Self-documenting code is an idea that's been around for many years, like stories about the wee folk...and like the wee folk, no one has seen self-documenting code.

The short version of the tweet series is that if you're writing code, you should be writing documentation as well - it's really too important to skip. This post, however, is not really about self-documenting code, but rather about how to write documentation, and more specifically a certain piece of documentation that you should never neglect.

---

I entered the whole techno-geek world at a time when computer labs were a real thing. Punchcards and shelves full of binders stuffed with documentation were commonplace. Documentation isn't like that anymore. When Java came along, I was almost enthused to use JavaDoc because of the level of clarity it added when writing the documentation. Now that nearly all code written by large, technologically advanced firms is either in Java or JavaScript (or ECMAScript), JavaDoc and JsDoc are - or should be - the de facto standard.

There is seldom serious argument against using one of these two tools anymore. There is disagreement about how the tools should be used, however. In the JsDoc community, one of the points of contention is the @author tag. To be clear, the JsDoc tool authors have stopped using the author tag and no 'contributor' tag has been added. It might seem, from their use (or non-use) that these tags are unimportant, and in fact, that is a common perception, especially in light of the advances in source code management, or what we used to call "version control".

However, not only should you use the authorship tag(s), you should be encouraging everyone else to use them as well.

It would come as a surprise to no one if I reminded you that we write code to solve problems. Not only are we writing code to solve problems, we're writing code to solve complex problems. For example, no one would write code to add two numbers...doing simple calculations on large data sets, perhaps, but there is a "complexity bar", below which we wouldn't dream of using code to address a problem. The first step of writing code is understanding the problem you're trying to solve.

As a hypothetical example, let's assume you've inherited a project. You've read the documentation that describes the solution to the problem the code offers, but after getting a small understanding of the problem combined with the solution being used, you have a list of questions. Why was this particular solution chosen over other solutions, for example. You can make some assumptions, but wouldn't it be nice to be able to contact the author to ask for their insight? Code, even well-documented code, is only a partial story. Just like every fan of a book turned into a motion picture knows, even faithful adaptations leave out bits that someone thought important. The first reason to include authorship information in your documentation, then, is the abundance of information it can point you to.

The common response to this concept is that the authorship information is not needed in the documentation because source control software, like git (my personal favorite), can track that information and expose it through tools like blame.

This response, however, misses the purpose of such tools. Version control is tied to a specific change...in git parlance, a commit. Yes, you can look at a particular line and see the last change of that line - the author of that change - but that is qualitatively different information than the author of a solution...and that information is generally only the last change. In order to get authorship information you must follow changes to a specific line back through history, and if at any point history was squashed or rewritten, that information is gone. Version control tools are excellent at solving the problem the author intended them to solve, as the author understood the problem; do not expect another author's code to solve a problem as you understand it.

Another reason authorship is important is we, as an industry...and really we as the human race...have difficult acknowledging the contributions of women and persons of color. The list of women who have significantly contributed in STEM fields without attribution is long...far too long. Not including attribution participates in that system of oppression by reinforcing the status quo. If we want to have any hope of disrupting patterns of discrimination, patterns that have existed for millennia, we must combat it at every turn.

A while ago I wrote a post called Visibility and Obscurity that described a situation in which attribution was changed on work I had done. In academia this is typically called plagiarism, and in most instances it's a punishable offense. Even outside academia, claiming to have done something you have not done can have serious consequences - Scott Thompson's resume scandal is evidence of that.

We should be writing code we can release with pride. Build things you're proud of and put your name on it...and give that same consideration to others. Amplify voices that are too often silenced or ignored - it does not diminish your contribution and it makes a difference. If it only makes a difference to the woman or person of color who finally has their contribution recognized - that's enough. If the only people who see an authorship reference are your employees, your colleagues, that's enough - they are important too.

Happy coding.

Coding education, coding life

I was recently reading yet another article about the importance of teaching coding to our kids¹, and it started my wheels turning.

Where, and when, I received my primary and secondary education, computers were these nearly magical devices that sent astronauts to the moon. Even at university computers were still heavily controlled with each student in computer science classes receiving an allotment of time in the computer lab with certain students able to use the punch card machine. Today, however, nearly all of us use computers to such a degree that we measure time we spend offline instead of online.

I certainly see the importance of teaching kids about computers, and about coding. The state of mathematics and science education in America is appalling², and anything that might improve education in sciences and maths should be encouraged. Further, the very idea of this blog - that we are paid to think - encourages thinking in many different ways, or at least it should.

However...

One of the questions Eric Larson asks demonstrates the difficulty I have with the focus on completely integrating "coding".

Is it really beneficial to have tenth graders memorize dates in history when they could just as easily Google them on their iPads? Or is it better to focus on how to track down and creatively, and productively, represent that data?

Here lies the issue. I agree with the implied answer to Larson's question - no, it's not beneficial to have tenth graders memorize dates in history...but then, it never has been, even before they could "Google them on their iPads". When Santayana said "those who cannot remember the past are condemned to repeat it" he did not mean those who cannot remember the dates of significant events are condemned to repeat them. It matters less the year in which Henry VII reunited the roses under House Tudor and more how he reunited them and what became of it. It matters less that the Battle of Clontarf was in 1014 than what effect that battle had on the political landscape of Ireland.

The only purpose dates serve in history is to help people organize events. A study of history should not be confined to memorizing dates any more than a study of literature should be confined to memorizing poems or a study of mathematics or physics should be confined to memorizing formulae.

As I recall, back in the days when we were allotted computer lab time, back when the Computer Science departments were still forming and companies were beginning to see the need for those who would program the behemoths that sat waiting to devour data, the insightful sought out imaginative, creative types who were also "pattern" thinkers - primarily philosophers and musicians - to fill the ranks, whether they had the functional and technical skills required or not. They saw the benefit to an education that had not integrated coding, or even the typical building blocks that coding requires.

I also recall that my sister was selected to participate in a computer programming "camp" for high school students one summer. She was, by more estimation than my biased memory, a "math whiz" and my family somehow managed to pull together the money that allowed her to participate in what we believed was a once-in-a-lifetime opportunity. Indeed, it was a transformational experience for her - she returned convinced that working with computers was not how she wanted to spend her life - she despised them, her interest in mathematics ended, and she focused on physical science and joined the medical profession. Though it is uncertain what effect integrating computers in her education would have had, we know the effect of repeated forced study of a topic on many people and can infer what might have happened.

Should we teach our children how to code? Yes, just as we would teach them mathematics or teach them how to think critically - how to recognize fallacies such as a straw man or ad hominem argument - or teach them to read. Should we switch curricula "toward tech or coding"? No. The focus of our curricula should be teaching children to think and what tools are available for their use and let them determine best how to apply them.

I love technology as much as the next person, but we are not all cut from the same cloth. We, as a culture, need more...more art, more music, more dance...more of what makes us human. Can technology take us there? Maybe. Should coding be more important than learning to play another instrument for the musician or learning to use another media for an artist or learning another style for a dancer? No. They are all tools.

Allowing students the freedom to use tools available to them, after they have internalized the lessons we can teach enables them to build the intellectual horsepower they will need to face a complex future and motivates them to meet it head-on. Doing otherwise would be as rational as, say, basing a curriculum on when a child was born.

Notes: links open in a new window

1. Larson, Eric. Coding the Curriculum: How High Schools Are Reprogramming Their Classes. mashable.com
2. US students rank 25th in math performance. Statistics About Education in America

Designing for Collaboration

I recently heard an executive (let's call her Ms. Foo) stress that collaboration is the key to success, and in order to collaborate effectively, a company needs to ditch the ubiquitous corporate artifact - the cubicle; therefore, (here's her hypothesis) eliminating cubicles and replacing them with an open floor plan is best for our organization. As further support for her hypothesis, Foo also has said that the cubicle is the epitome of a closed corporate culture and that high-performance companies (e.g. Apple, Facebook, Google, and Twitter) don't have cubicles.

As an exercise in critical thinking, let's quickly examine Ms. Foo's arguments - by first examining the argument for fallacies and then examining the veracity of the statements can we determine whether or not Ms. Foo makes a valid argument.

Let's first examine Ms. Foo's argument that 'collaboration is the key to success'. In its present form, this argument is clearly a sweeping generalization. Even if the statement were qualified to her own organization in the more precise 'collaboration is the key to our success' it's still arguably not precise enough and is not as precise as would be "collaboration is a key to our success". By increasing precision we can easily see that maintaining the argument in its presented form also creates a false dilemma.

Let's next examine the statement that 'the cubicle is the epitome of closed corporate culture' (and the connotation that such a culture is not what Ms. Foo wishes to represent). To better examine this, we will ignore the hyperbole and better express the argument as 'closed corporate culture promotes cubicles' - for certainly the epitome of 'closed corporate culture' would be a office door - or at the very least, something that can be physically closed. I would put forward that although Ms. Foo's original argument is a lightly veiled guilt by association, our restatement of her argument is clearly an example of such a fallacy.

Let's next take the statement that 'high-performance companies don't have cubicles'. Even if the statement is factually correct, and I am not in a position to argue that it is not, it still remains an argumentum ad populum. Perhaps what Foo intended was to present evidence that 'high-performance companies' have implemented a collaboration-promoting floor plan and found it beneficial. If this argument is intended as evidence, let's restate it so that it may more closely represent the evidence she intended - let's instead say high-performance companies have implemented an open floor plan and have seen an increase in collaboration.

Even though our more semantically precise argument doesn't fall into the argumentum ad populum, such changes in environment design are seldom executed under the strict controls normal experiments fall under and without control groups it is typically impossible to determine the veracity of the premise. Without demonstrating a causal relationship, the argument is, at best, subject to cum hoc ergo propter hoc or perhaps to post hoc ergo propter hoc.

It is clear that Foo's arguments are fallacious; however, that does not mean that the conclusion (that open floor plans are best for her organization) is necessarily false, simply that it is unproven, so let's continue the exploration.

There are additional problems with Ms. Foo's proposition; for example, it's rife with ambiguity. Perhaps by clarifying this ambiguity we can come to a restatement of the argument that is not fallacious - one for which we can examine the veracity.

First, it's not, generally speaking, as if a person chooses to either collaborate or not, but rather they choose, consciously or subconsciously, the degree to which and manner in which they collaborate; "collaboration" is not an all-or-nothing one-size-fits-all proposition. Further, Ms. Foo uses the term success without actually defining how success would be measured. Success may be defined as high productivity, as it is in many cases, or high innovation, or perhaps high engagement among the employees.

Ms. Foo's original argument might therefore be restated as collaboration in the manner I understand it is one of the keys to what I define as success for our organization; a floor plan that does not use cubicles, such as those employed by Apple, Facebook, Google, and Twitter, creates the type of collaborative environment I desire; therefore, eliminating cubicles and replacing them with an open floor plan is best for our organization. This restatement clarifies many of the points of ambiguity, yielding a much less fallacious line of reasoning; however, it also makes Ms. Foo sound a tyrant and generally undesirable boss.

I should point out at this point that I've not ever been to any of the companies classified as 'high-performance companies' and cited by Foo, nor can I say reliably that collaboration is not a key to success for her company. I can say that I have, in more than a couple of decades in the industry, worked in a variety of environments - everything from 'open floor plans' to an office with a door, and while I would avoid a hasty generalization, or other fallacy, there may be other factors Ms. Foo has not considered.

In my experience, each organization in which I have worked has had a variety of concerns that weren't related to collaboration that influenced the work space configuration decisions. The most pronounced concern has typically been security. My experience has been that the greater the need for security, the more restricted the work space is. Basically, in the work environments where security was highest, my workstation was behind a locking door and few people had access. Collaboration within environments with strict security is, undoubtedly, lower as knowledge and activity is compartmentalized; conversely, collaboration within environments with lower security is higher.

I would also say that I am generally supportive of collaboration - in fact, I would put forward that the teaching method named for one of the world's most famous philosophers is based in collaboration between student and teacher. In my opinion, it could easily qualify as a key to success in many organizations.

With those qualifications being disclosed, I'll continue, using, instead of Ms. Foo's original argument, the restated argument, and looking to the veracity and whether or not it follows from beginning to end.

First, I believe there is little room for doubt that physical environments can affect collaboration. The argument that a floor plan that does not use cubicles facilitates an open and collaborative environment may be true. However, possibility is not actuality, and I do not believe that an open floor plan is either a necessary or sufficient condition for collaboration.

There are, in my experience, a number of things that hinder collaboration. I would separate these hindrances into physical and non-physical obstacles. Non-physical obstacles typically include who can collaborate but also go beyond into how individuals are encouraged, or even allowed, to collaborate. In fact, I would posit that physical obstacles to collaboration, whether it be minor physical barriers, such as a cubicle, or more significant physical barriers, such as lacking a physical presence in a location (e.g. telecommuting), are less significant than non-physical obstacles in the face of technology, primarily because they are easily controlled. We can easily move into shared physical space in the case of cubicles or use email, phone (whether land-line or mobile), and instant messaging when lacking a shared location. In fact, organizations distributed across the globe typically use a combination of these tools and more to collaborate.

Since the non-physical barriers to collaboration - for example, a culture that does not value the contribution of specific individuals, whether that is because of their role in the organization or their position in the organizational hierarchy - are generally both more significant and more difficult to address and control, these issues should be addressed first. Seeing a physical environment as the obstacle to collaboration is a red herring, especially considering the number of methods available to work around physical environments. Further, because the features of a physical environment that affect collaboration can so easily be bypassed, we might conclude that if those features affect collaboration, and it hasn't been demonstrated that they do, that result is desired by at least one party to the collaboration. In other words, the processes for collaboration must be addressed prior to the environmental issues that may hinder collaboration, in part because it is quite possible that the very environmental issues seen as obstacles to collaboration may serve another purpose within the organization.

As an example, lets assume for a moment that one party in our 'collaboration' model has a constraint that creates an inverse relationship between a success and interpersonal interaction. If such a constraint existed, would it not follow that productivity would be improved in those situations where the amount of interaction was controlled? If physical barriers are easier to overcome - to manage - would it that factor not make it the preferred control? If we can see an affirmative answer to either of these questions, then is it not a simple matter of asking ourselves "can such a constraint exist?" The answer to that question is a definitive "yes" - AD/HD is a physical condition (and an ADA protected class in the US) that creates an inverse relationship between many measures of success and interpersonal interaction.

We've seen how this argument applies to cubicles, but how might the same general thought process apply to another collaboration-reducing environment, telecommuting? It is in this question that we will demonstrate the importance of the ambiguity of the word success as well as collaboration.

We can be certain telecommuting is a greater barrier to some forms of collaboration than cubicles, because at a very minimum the accidental interaction while moving through shared space is no longer available and intentional interaction must be attended to in greater detail. It seems after a two-month silence that perhaps this collaboration was what Marissa Mayer intended to address rather than productivity.¹

In making statement that telecommuting is a barrier to face-to-face interaction she has, to some degree, stated the obvious. However, she goes on to claim that people are more collaborative when they are together - in itself perhaps not a wild claim - and that it follows that they are more innovative. It is unclear whether this last statement is wishful thinking, a hasty generalization, an instance of post hoc ergo propter hoc, or an evidence-based claim.

Mayer clearly defines success as generating ideas (product development) rather than delivering on those ideas (productivity). By defining success, not as productivity - which has been the generally accepted measure of success - but as the generation and conglomeration of ideas, Mayer may have made a potentially workable argument for a direct relationship between what she means by collaboration and success; however, it is not a foregone conclusion.

If we define success as the generation and conglomeration of ideas, it might seem reasonable that we ought to look to increase collaboration; or at least interaction, including accidental interactions; however, we ought also recognize that the increased interaction comes at a cost. Further, we ought also recognize that the cost we pay in one area may not show a benefit in another. For example, it would be possible to decrease productivity without increasing collaboration or the generation and conglomeration of ideas.

Finally, even if the elimination of all physical barriers increases collaboration, which has not been proven by either Ms. Foo's arguments, or Marissa Mayer's, does it follow then that the increased collaboration is good for an organization?  Not necessarily, and that's where the design comes in. Without adequate design, one that balances the cost against the (real or perceived) benefits, increasing collaboration is destined to fail; otherwise, edicts intended to promote collaboration leave organizational members who have little chance to contribute to the discussion feeling disenfranchised and generally dismissed by a tyrant, and that environment is definitely not conducive to collaboration, or in fact anything other than self-protection and evasion.

Notes

1. Marissa Mayer Finally Addresses Work From Home Ban

Fear is the birth of cruelty and the death of reason, wisdom, and finally, action. (Robert's Rule #26)

Fear, as our 'leaders' have discovered, is a powerful motivator. For most people, one of the most powerful fears is of losing their job, in fact, for some people, the fear of the loss of their livelihood is even stronger than their fear of death, because it means something very significant to those who depend on them. Because of the power of this fear, employers the world over become some of the most powerful entities known. However, this fear comes at a price, for fear is the birth of cruelty.

When you, as a manager, threaten someone's job and engage this powerful motivator, your 'direct report' will likely tow-the-line. They will likely become quite complacent. They will also likely quit innovating, start protecting their assets to the detriment of the team, and start looking for a place of employment where they believe they will be respected, which means their productivity will generally plummet and they will become a drain on morale. In short, what you will have created is a negative reinforcement cycle that will likely spiral out of control.

On the other side of fear, however, the lack of fear is an equally strong motivator. The lack of fear can be the result of either having nothing more to lose or a true feeling of safety.

The lack of fear that is the result of having nothing to lose - that finds its origination in desperation - is dangerous in the extreme, as The Art of War notes. It is the recognition of this fact that has led companies to treat terminated employees as criminals as they are escorted from the building, often without even being given access to their personal effects. The creation of this type of 'enemy' is a mistake of the highest order and you should always try to maintain the appearance that even those discharged have something more to lose. Helping them move on to another position (if that is at all possible) is a good start. After all, just because they don't fit in with your organization that does not mean they would not fit in quite well somewhere else. If you can honestly, objectively review their contribution you will (nearly always) find some benefit they provided to the organization that you can leverage as they look for another position.

On the other end of the lack of fear spectrum - when a person feels safe in their job - people are more likely to take risks, stretching and growing. They are also likely to innovate, be more relaxed and positively affect team morale, in essence become a powerfully positive asset. It is the creation of these positive reinforcement cycles that we need to create. One of the most powerful effects of these positive reinforcement cycles is the energy they contribute to the team, as study after study has shown that 'winning' begets 'winning' and nothing so strongly counters winning than fear and trembling, because fear is also the death of reason, wisdom, and eventually, action.

When working with rock stars, get your M&Ms ready (Robert's Rule #6)

[Tweeted 2011-05-02]

Most managers I know claim that they would love to have a team of rock stars. Most of the time it's pretty clear that's because a team tends to make a manager look awesome (or not). It makes sense that managers would conclude that a team of rock stars would make the manager look like a rock star as well. Not all teams are comprised of rock stars though, and those that are tend not to maintain cohesion.

For a while I tried to determine why this is the case...why is it that a group of people, especially one where the majority is highly skilled, would spin apart after a period of cohesiveness. Here's what I've discovered: highly skilled people tend to not only be highly skilled but also have their own style, and everyone else's style is not as [insert your descriptor here]...and, simple as that, you find your rock star has become a diva, a word that has connotations beyond the "star" quality that it denotes.

There are two ways I've seen managers react to divas on their team:

• they tighten control as much as they can, making sure the "diva" knows the manager is in charge
• they stay out of the way of the "diva" as much as possible, working behind the scenes to make sure the obstacles are cleared

Having been on both sides of this particular equation, allow me to share the following. Reacting by making sure the diva knows the manager is in charge will backfire. The manager may be in charge, but yanking a dragon's chain seldom ends well. At the very least, the rock star will become miserable and rebel, reducing team morale and in some cases the rebellion has resulted in political intrigue that results in the termination of one or more of the parties. Keep in mind that even as a manager, you're only in charge as long as you're actually employed and have employees reporting to you.

In contrast, one of my best managers, one who dealt with several highly skilled technical people, all with strong personalities, said her formula for success was to hire rock stars and stay out of their way. That she enjoyed the success of a team that delivered solid, feature-rich, complex products ahead of schedule and under budget with extremely low defect rates is a testament to the validity of her approach.

She didn't sweat the small stuff and made sure that her team was rewarded adequately, and most importantly, she made sure that even if she didn't initially understand the reason for a request, she tried to move towards honoring it at the same time that she sought to understand it because, as it turns out, rock stars tend to have very good reasons for seemingly odd-ball requests (one of the most famous examples).

All this led me to Robert's Rule #6: if you want your team to be rock stars, expect a few divas and get those M&Ms ready.

Vision without action is a dream, action without vision is a nightmare (Robert's Rule #5)

[Tweeted 2011-04-29]

We'll start off a short post with the rule today. A vision without action is just a dream; action without a vision is a nightmare (Robert's Rule #5).

One of the things that I have consistently argued against in every organization I've worked for is what I call "Getting Shit Done Syndrome", or GSD. (Feel free to think of it, or call it, "Getting Stuff Done Syndrome" if you'd like.)

There's a simple argument behind this that goes something like this...

• If you're in "information technology" then you're in a knowledge economy
• If you're in a knowledge economy then your product is knowledge and information
• If the product is knowledge and information, that requires thinking more than doing
• Therefore, you're paid to think, and then do, not just do

I cannot even begin to name the times I've seen my fifth rule in action; the number of examples I could give are countless. So, rather than pull out one experience from hundreds, I'll just say that if you don't consider this rule valid prima facie then our experiences are so different we may not be able to find any common ground.

Past performance does not guarantee future value (Robert's Rule #4)

[Tweeted 2011-04-28]

A while ago I was in a job managing a team of software engineers. This team was a mix of people; both in terms of experience and in terms of relationship to the company (i.e. some were full-time employees and some were contractors).

Now, I tend to consider myself more detail-oriented and data driven than the average person, so it made perfect sense to me to relate software features to be developed, and all the project management related data (estimates, dependencies, etc) to my assessment of a developer's skill level and also relate the defects found to the features. In hindsight it was, perhaps, a tad more complicated than it should have been. On the positive side, it gave me quick insight into how effective my assessments were and how likely we (as a team) were to hit our projected development milestones.

One of the problems I faced was when developers took up a different task or a different language. Software development, as a discipline, is fairly straightforward. There are language skills (computer languages are made up of nouns and verbs and have direct and indirect objects just like other languages) and general concepts (like data normalization rules and network/communication protocols) that apply to all feature development, so a good developer is a good developer, right? Usually.

Usually good developers get better, but practice doesn't make perfect and a developer that handles one language with ease may not be able to make the switch to another language. Such was the case when one of the developers on my team attempted the switch from COBOL to an object-oriented language. When he popped the clutch on his paradigm shift (yeah, I started that saying back in '93) his development shuddered like an old car. In a car, if you pop the clutch, you can stomp on the accelerator and rocket off or you could try to coax it along and kill it...I believe that in theory it works the same with people.

This experience led me to conclude that "past performance does not guarantee future value" is just as true for people as for the stock market (Robert's Rule #4). This developer chose to try to coax his development along rather than immersing himself in the new technology. I don't know where his career has taken him in the years since, but it's most likely out of software engineering.