Karl Oscar Weber

Documentation Matters

Good documentation absolutely matters. It's the difference between code being useful or an obstacle. The whole point of documentation is to teach the why and how of something. If the documentation doesn't allow quick and thorough understanding of your code, then the documentation has failed.

Documentation must be approachable for newcomers.

You need comprehensive beginners tutorials that cover all of the topics in macro. New Customers, as Jack puts it, want to feel empowered right away and each one is different. Covering the topics in macro help someone to learn the general concepts of your code before they look at specifics. Care must be taken write with common words. If there is an uncommon or obscure word then link to the definition. Make it as easy as possible for someone to learn all about your code.

You must also be very specific. Some people have a very specific and short term need for code, they want to get in, understand what they need to get the thing working, and then be done with it. Usually these are users that have been using your code for some time and want look something up very quickly. micro documentation also helps to teach the more powerful parts of your code. When a learner feels capable with your widget they will use it more often, and be more likely to contribute to your project as well.

Documentation must be approachable to you.

It's more important than commenting your code. If comments out number your code, then your code will be easier to maintain. Double so if your documentation outnumbers your comments.