update: advantages of software documentation

Author: practicalli-johnny

docs/blog/posts/advantages-of-software-documentation.md

@@ -9,7 +9,7 @@ categories:
   - documentation
 tags:
   - documentation
-draft: true
+draft: false
 ---
 
 
@@ -36,33 +36,36 @@ As well as making the code base more useful, creating documentation on a regular
 
 * 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
+* 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
 
 
-Figuring out someone elses code by itself adds a lot of overhead
+!!! WARNING "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.
 
-If developers take on the challenge of learning the skill of writing good documentation to the extent they do writing code, then they would soon be writing good quality code very quickly.  Then all of these excuses are mute
-
 * 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.
+* 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.
 
 
+!!! TIP "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.