How programmers, coders, and software engineers can get over “documentation avoidance"

             


Posted Sept. 26, 2018

Coding is an unsung art. It requires skill, creativity, and care to craft a program – or even just part of a program – that can help its users in a functional way. These professionals should be rightfully proud of the work they produce.
 
Documentation, though? Documentation is typically an afterthought, if it’s tackled at all. All too frequently, any documentation or computer science writing represents only a half-hearted effort, something the coder forced him- or herself to do before starting their next “real” project.
 
However, anytime you are reluctant to write documentation to accompany your code, you’re diminishing the impact your code could have. The less people understand your work, the more they will assume it’s not for them (or fail to understand how to use it), and the fewer people will actually use it.
 
This is particularly critical if you write open-source code and would like contributors to join your project. It is your documentation, not the code itself, that will generate enthusiasm and excitement. Indeed, code isn’t truly finished until documentation is prepared. How else will you communicate its purpose, its benefits and advantages, and its functions? Code without documentation risks going unused or, in extreme cases, even backfiring on the user.
 
Documentation can include:
 
  • “README” files, which are usually the point of first contact with potential users and others. The README explains what the project is, its reason for existence, and how to get started with it.
  • “Frequently Asked Questions” (FAQs) that answer common questions and help readers to better understand your product and its intricacies.
  • Programming documentation. If you are working with colleagues or collaborators, you might produce internal documentation that facilitates their involvement and understanding of the code.
  • And more. Anything that explains, contextualizes, and assists users and other developers can be incorporated into documentation.
 
How can you make it easier to develop such documents?
 
  • Write consistently. Although “batching” your writing tasks after completion of the code may seem like it would be more productive, developing an ongoing writing habit will create a smooth rhythm that will facilitate document production.
  • Document as you go. If you already leave comments in the code itself, try to be a little more descriptive with them, and you’ll already have a great start on your documentation.
  • Take an engineering approach. Treat writing projects like engineering problems. By thinking of writing as a different kind of coding – which it is, in many ways – it may help a code-minded person tackle the job.
  • Develop your writing skills. Writing, like coding, is based as much or more on skills as on talent. It’s natural to put off the tasks with which we feel less comfortable. Develop your writing skills, and you’ll feel much more confident about – and less resistant to – writing the documentation that completes your code.
 
About Hurley Write, Inc.
 
Hurley Write, Inc., a certified women-owned small business (WBENC and WOSB), Historically Underutilized (HUB), and Disadvantaged Business Enterprise (DBE), has been designing and teaching customized onsite and online technical, business, and scientific writing courses for over 25 years. We also develop and teach specialty courses, such as how to write proposals and standard operating procedures (SOPs) and deviation and investigation reports, and how to prepare and give great presentations.