Developers love to code or solving problems with code. One thing they hate, and don't want to be reminded (time and again) is to write documentations.
Later last year (in 2016, if you are reading this after year 2017), when our team decided to follow the Agile Methodology, Scrum Framework to be exact, and we defined our "Definition of Done" (DoD), one of the items that made the definition was "to include good documentations, that is well written and easily understood by others", to be written. As I peer-reviewed codes coming from pull requests, I realized that some of my colleagues didn't know what a Javadoc comment is and/or how to write (and/or even generate) it so I gave them a brief introduction to Javadoc.
Initially, code comments were 1 liners, then it gradually improved and eventually faded to black, i.e., no code comments existed anymore.
Please note, I am including code comments as subset of the technical documentations. When I inquired about the lack of comments/documentations from the team, various reasons popped up:
- Time constraints: Our sprints were (usually) a 2 week sprint, with a sprint review happening on the last day of the sprint. Due to (unforeseen) circumstances, the team realized that development and testing were crucial to completing the sprint and documentation needed to take a back seat, if the code were to be released on time.
- Grammatical errors: We allowed other developers reading comments and documentations and trying to understand what the code was about, without them reading the code. Let's just say that many of us will need to retake High School language courses again.
- Articulation is hard: We, as developers find it hard to articulate our code into documentations that is simple to be understood by their target audience. For example, a good code comment must be understood by other developers in such a way another developer could rewrite the piece of functionality and it would produce the same result based on the pre/post conditions set and returned to/from it.
- It's not fun: No developers like to sit the entire day writing documentation. It makes their day take forever.
When I started my career in development, everything had to be documented: Code comments, functional technical document, test case documents, etc. We may hate it but it has to be done.
So, why do I want to encourage my peers to start writing documentations as if they're writing a novel? These points might help:
- Self peer-review: I have found and fixed various unknown bugs and horrendous codes when I document my work (to a point you even say, "What was I thinking when I wrote this?").
- You might revisit your code in the (not so distant) future and your documentation can help you bring back your train of thoughts on why the code was written in that manner.
- Versioning: I have not work in an organization where business stick to their business requirements from beginning to end. Requirements changes and often very frequently too. Without documenting and versioning your documentations, there is no audit trail of the changes of the requirements that has been implemented. In the long term, you want to protect yourself if requirements change in the detriment of business.
- Quality of work: A well documented code, technical document shows that you have taken time to research and put thoughts into writing the document. Essentially, you will treat your documentations the same way as you would treat your customer: you wouldn't want the customer reading your documentation(s) and feeling uninspired by your work, or yet, not wanting to work with you again.
- Good image: The more you write documentations, the better you become at writing. Eventually, your client will be known to release good documentations consistently and that boosts morale and good image: for you and your organisation.
Writing documentations sucks, but one has to start somewhere, right?
Good luck! I know I will have to discipline myself into writing documentations too.
Comments
Post a Comment