Advantages of writing documentation for code
Code that executes correctly and provides only limited value to the business can still be a huge maintenance burden.
Code is very rarely written to include why is was added, what is the purpose of this code.
Dismiss the value of adding documentation that describes the why of the code significantly increases the cost of maintaining and extending that code. Skipping documentation adds to the engineering debt of any solution (even when the intention is to re-write that code).
Value of regular documentationλ︎
As well as making the code base more useful, creating documentation on a regular basis:
- communicate more effectively with the wider business
- increases communication skills
- opportunity to learn more words
- get better at writing documentation
- become faster at writing documentation
-
becomes easier to update and extend documentation
-
write better code - code tends to be much clearer if the person writing it has writing skills (better choice of names, smoother flow, more organised)
- retain more knowledge in a persistent storage service (blog, tutorial, notes)
- share knowledge with others effectively
- minimise the need to answer the same questions over again
- get feedback from others
- become a more productive team as learning is shared and not redone over and over again
Overhead of poor or no documentation
Figuring out someone else's code by itself adds a lot of overhead and that someone else can also be you a few months (or even weeks) ago.
Typical excusesλ︎
Most excuses not to write documentation really come from discomfort and even fear about a persons writing ability. Ironically this is often quite a rational fear as writing good documentation is another skill to learn.
- dont have time - documentation saves a huge amount of time overall
-
not paid to write docs - actually you are paid to create projects that other people can work on readily (without docs then people on-boarding to a project spend a lot more time reading the code - and probably end up rewriting it so they understand it)
-
documentation doesnt keep up with code changes - an extension to the dont have time excuse. If the thoughts in a persons head are written down succinctly or a summary of changes to be done to code then is just as easy to update the docs when changing the code. Actually updating the docs is a valuable way to ensure a person understands the changes they are going to make (saving time debugging a system or dealing with issues by lack of understanding)
-
dont like tool x, its slow - a very poor excuse. Notes can be written as text / markdown / org whist writing code and then pushed to what ever collaborative knowledge share tool is used. Doc tools are like any other coding tools,
-
I dont get paid enough - a systemic problem meaning a person feels significantly undervalued within the company, therefore it is likely that most of their work will be of just enough quality to work but relatively challenging to work with.
-
code is the documentation - a mixture of insecurity about docs and/or lack of experience of software development overall. They have not make the connection that documentation provides a way to quickly recall previous experiences and build a greater level of skills.
Practicing writing skills overcomes excuses
When developers take on the challenge of learning the skill of writing good documentation, to the same extent they do writing code, then writing good quality code becomes far easier very quickly. Then all of the common excuses become mute.
Thank you.
Practical.li Website