IDG Contributor Network: Are women better at code documentation than men?

Software developers do not program in machine code. Instead, they use compilers and programming languages to code in high level language, which in turn generate machine code. Not that it’s impossible to learn machine code.

But why bother when you have awesome programming languages like JavaScript[1], Python, and C++ to do the heavy lifting for you. However, software development is not a one-off activity, it is an ongoing process of constant maintenance, regular updates, and proper documentation. Proper documentation adds “readability, transparency, stability, and trustworthiness to your application and/or API”(Dzone)[2].

Most male software developers have no problem with writing codes to debug and update, and create cool toys, but what they have a hard time doing is maintaining proper documentation.

[ To build or to buy IT applications?[3] InfoWorld sheds light on this eternal questions. | Cut to the key news in technology trends and IT breakthroughs with the InfoWorld Daily newsletter[4], our summary of the top tech happenings. ]

Emilyanndd[5] is a programmer who broadcasts on Livecoding.tv. Emily is from San Francisco, CA, and her favorite language is Python.

While there are no research or studies on the subject (and probably there should be), other studies and research on topics such as “Do women write better code than men?” and “Are women better at multi-tasking than men,” do shed some light as to why Women are better at code documentation than men. So let’s explore this phenomenon.

So why are women better at code documentation than men:

1. Men don’t know how to write

According to Jacob Kaplan-Moss at Jacobian.org[6], and one of the writers for Django, “The best way to learn how to write great documentation is to first learn how to write.” The number one reason women are better at code documentation than men is that most men simply cannot write. In a 2009 article in Fast Company[7], Lydia Dishman asked the question, “Are Women Better Writers Than Men?” To answer the question, she turned to Erin Belieu, one of the founders of WILLA, an organization dedicated to bringing attention to women’s literary accomplishments.

To which Belieu responded, “Sometimes they are, sometimes they aren’t.” However, in a Grammarly[8] survey of 3,000 people of which 54% of the respondents were men, the results showed overall, 59% of men and women believe that women are better writers. It further showed 65.5% believed men were more likely to write short descriptive sentences, while 75.8% said women were more likely to write long descriptive sentences.

Grammarly concluded, “Women tend to be more descriptive in their writing…perhaps as a result, women are generally regarded to be better writers than men.”

2. Men don’t enjoy typing

Another reason women are better at code documentation is tied to number 1: Men just don’t enjoy typing. But according to Steve Losh[9], a confessed lover of code documentation, in addition to writing, typing is another very necessary skill for code documentation. “To write great documentation, you need to be able to type.” Practice is the only means by which you can acquire professional typing skills, but online data shows that girls do really enjoy practicing their typing skills[10] more than boys.

3.

Women are better at multi-tasking

In a 2013 experiment[11], researchers discovered that women are better in multi-tasking than men. Arguably, women are not good at doing multiple tasks simultaneously. Hence, multi-tasking in this sense is analogous to a secretary answering phone calls, filling out paperwork, and sorting mail, but not necessarily all at once.

In code documentation male programmers “answer phones,” caring to leave the “uninteresting” task of code documentation to some lesser god.

4. Men have no patience

Another reason women code better than men is that men have no patience. In a 2011 survey[12] of 3,000 respondents, conducted by One Poll in the United Kingdom, researchers found men were more likely to snap quicker than women.

Five out of ten men said they would wait up to a minute when asked how long they would wait (for anything) before walking off in a huff, but only ten percent of women said they would leave that quickly. Code documentation on a whole, is a time-consuming process. Ironically, you cannot code efficiently without patience, but that seems to be where men’s patience end.

5.

Real programmers don’t write documentation

This fifth reason is perhaps the most pervasive and is clearly a myth: The idea that real programmers don’t write documentation. This position is particularly irresolute in agile software development where developers try to avoid any redundant activity that do not bring direct value. In particular, the Agile Manifesto supports “working software over comprehensive documentation,” which to some extent could be interpreted as “We want to spend all our time coding.

Remember, real programmers don’t write documentation.” (letters.pdf)

6. Men are not good at expressing emotions

Men are not good at expressing emotions simply translates into men are not good at communication. “A solid foundation of good written communication skills is an irreplaceable prerequisite to code documentation,” (JKM[13]). Men are not encouraged to show emotions, so they bottle up their feelings.

This lack of expressiveness spills over into the physical making it difficult for men in general to write things down. They can code because that requires a “scientist mindset,” but documenting, which requires the ability to communicate is not their forte.

7. Automatic Code documenter

Finally, women are better at code documentation because they practice by hand instead of depending on auto-generated documentation[14].

Men, on the other hand, often resort to using tools such as Doxygen, NDoc, Sandcastle, and others, to auto-generate the code documents. This idea of using the automatic code documenter is attractive to male programmers for many reasons some of which are already stated. However, according to Kaplan-Moss, “Auto-generated documentation is almost worthless.” Auto-generated documentation has no fluent voice.

At the end of the day, nothing beats code documentation that is “written, organized, and edited by hand.” This will require more typing, which ironically, men don’t enjoy doing. But in the long run the results will be much better. Code documentation, the process by which programmers document their code, is a necessary process in software development.

However, due to men’s reluctance to practice their writing and typing skills, the myth that real programmers don’t document, men’s lack of patience and, women being better multi-taskers, and the obvious fact there are automatic code documenters, which are attractive to men, women are better at code documentation than men. Interestingly, a February 2016 study[15] showed women were considered to write better code than men as long as they didn’t reveal their gender. What this really means is that women do write better code than men.

However, if the men found out the code was written by a woman they would reject the code. But that’s the subject for another article. For an interesting spin on the subject you can read next article, “Why Developers Write Horrible Documentation and How to Solve It.” In it he advocates video documentation as the obvious solution for programmers who write “horrible” code documentation[16].

So what do you think? Are women just overall better writers and documenters of code than men? Document your views in the Comments box below.

This article is published as part of the IDG Contributor Network. Want to Join?[17]

References

  1. ^ JavaScript (www.liveedu.tv)
  2. ^ (Dzone) (dzone.com)
  3. ^ To build or to buy IT applications? (www.infoworld.com)
  4. ^ InfoWorld Daily newsletter (www.infoworld.com)
  5. ^ Emilyanndd (www.liveedu.tv)
  6. ^ Jacobian.org (jacobian.org)
  7. ^ Fast Company (www.fastcompany.com)
  8. ^ Grammarly (www.grammarly.com)
  9. ^ Steve Losh (stevelosh.com)
  10. ^ typing skills (www.ratatype.com)
  11. ^ 2013 experiment (bmcpsychology.biomedcentral.com)
  12. ^ 2011 survey (pressreleases.responsesource.com)
  13. ^ JKM (jacobian.org)
  14. ^ auto-generated documentation (blog.liveedu.tv)
  15. ^ February 2016 study (www.independent.co.uk)
  16. ^ horrible” code documentation (dzone.com)
  17. ^ Want to Join? (www.infoworld.com)

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *