Update index.md (#29155)

This article seemed a little light on content and examples. The grammar was also a little off.

I have re-written the article to include more examples, cleaned up the grammar, and included a "further reading" suggestion.

guide/english/documentation/index.md

@@ -3,9 +3,13 @@ title: Code documentation
 ---
 ## Code Documentation
 
-Code Documentation allows other developers (and yourself) to understand/remember the customs and purposes of particular pieces of code. It is recommended to use documentation before debugging your code, this helps you to debug effectively.
+Code Documentation is the tool developers use to make the purpose of their code clear. It's also called Commenting, but it's about more than just the comments you include with your code. It includes how you space and indent your code, name your variables, and give titles to various sections so it is easy to read and understand.
 
-For example, if you happen to pass along your code to an absolute beginner, they should be able to follow along through comments, appropriate variable names and that means structuring the code in a readable manner. 
+Code Documentation lets anyone (from newbie to seasoned expert) quickly get comfortable with the customs of the particular module, functions etc for a particular programming language. For example, if you pass your code to an absolute beginner, they should be able to follow along. Here is an article from Harry Roberts at CSS Wizardy Ltd. (https://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) about structuring class names in CSS. This is just one example of good code documentation.
+
+An excellent example of the value in good code documentation is the debugging process. The first step in debugging is to read the code documentation, right? But good code documentation goes beyond a readme file or header comments. Code Documentation means commenting every function, loop or declaration. It's having, and following, a variable naming process. And it means spacing and indenting your code so it's easy to read.
+
+There is always the danger of over-commenting your code, too. Here is a video from Brian Voong where he discusses this danger and how to avoid it by using good naming conventions. (https://www.youtube.com/watch?v=2-KBQsTo8AY)
 
 It is extremely important to make a habit out of commenting your functions, loops, and declarations and treating comments as part of the source code, just as regular code should be.
 
@@ -13,6 +17,7 @@ Many developers have probably learned that it is much harder to go back through
 
 Think of Code documentation as a history textbook. It allows current developers to keep tabs on their progress, as well as to educate future developers. Use it not only as a learning tool, but also as a reminder. As George Santayana once said, "Those who do not read history are doomed to repeat it!"
 
+Have an interest in learning more and building your coding skills? Have a look at FreeCodeCamp.org. They have thousands of hours of free instruction that include how to comment and organize your code so it is well documented.
 
 ![An example of commenting in the real world](https://cdn-images-1.medium.com/max/1620/1*Pyxsc7Uixbitv5myywaA_Q.jpeg)