Documentation: The Lost Art

Overview:

If you have made it this far in your career and have not been lectured on the importance of documentation, told you needed to improve your documentation skills, or that you do not do enough documentation I applaud you. . . seriously, I really do. Documentation is the bane of my existence and the only thing I hate more than doing it is maintaining it. usually get sucked into either going deep into the weeds or glossing over minor details in my documentation; both of which do not help anyone. Today I am going to share with you some tips I have learned over the past couple years on ways to more easily create and maintain documentation.

Documenting Your Code:

Here is the deal, document your code IN YOUR CODE! Do not have external documentation in a wiki or some other thing for code you write. Also do not have full documentation inline.

README Files:

Be very diligent about creating a concise and informative README file. I have found it best to create a generic template and then fill in the blanks. If there are sections that do not apply. . . remove them. All of my README files include the following:

• Table of Contents

• Overview

• Description

• What it Affects

• Requirements

• Usage

• Reference

• Limitations

• Development

• Release Notes/Etc

Not all of those sections are mandatory but it is a nice template to try and follow. If you are not a fan of README files then you can document in your code.

Documenting in the Code:

As I stated above I am not a fan of inline documentation, it is fine for comments and such but is not the place for actual documentation. My preference is a full block of documentation, commented out, before your code even begins. This documentation can follow the same outline as the README file, or be more concise like the example below:

• Description

• Parameter/Variable descriptions

• Requirements

• Release Notes

Your Code, Your Choice:

Whichever one you decide to go with is the right answer, not documenting is the wrong answer. Documenting outside of your code in a wiki or somewhere else technically is not a wrong answer until it comes time to update the docs. I find it far easier to update the docs with a commit/PR that has new features and fixes then to update the code and go somewhere else and update the docs.

Documentation Articles:

When you have to write documentation that does not relate to code you are usually writing a wiki article or using some sort of other shareable tool. I am not going to go into organizing landing pages and tags and all those other features and things you should be doing to make your documentation read like some sort of manual/book. I am going to focus on a single article.

Formatting:

I am going to be brief and blunt here. Nobody likes reading a wall of black text on a white background. It is boring, it does not hold the attention of the reader, and quite frankly it is not fun to do. Formatting can be hard, and time consuming but when all is said and done you have a nice looking page that reads easily and quite honestly you actually feel like you have contributed something worth while. Please take your time and careful consideration when deciding how to format your document because it can be the unknown decision maker if someone thinks what you wrote is useful/accurate or if you half-heartedly threw some words on a page.

Content:

Level of Detail:

Try not to dive deep down into the weeds with your documentation. That level of detail can be discussed in a chat or one-on-one. The goal should be to provide enough detail to get one started and allow them to have enough information to make some decisions that the documentation does not directly address. Every unique scenario or option should not be vital to your documentation. Think more along the lines of quick start guides. You can add more detail than your typical quick start but remember, too much detail and too lengthy you will lose readers.

Videos and Screenshots:

Both are great in theory; both get out of date very quickly. Unless you plan on being diligent about keeping these visuals up to date stick to well formatted wordings. . . is that a word?

If you are creating detailed documentation for something specific then these visuals might be a better fit and change less frequently.

Editing and Review:

Do not review your own documentation. It is likely you will not realize you have skipped important n00b information or have gone off the rails technical. Have someone with less knowledge than you do your review. See if they find it confusing or constructive. Ask them if they feel anything was left out. These people are your greatest resource. . . use them.

Conclusion:

That is my spiel. I hope it helps and I hope I kept your attention. Just remember your primary goal is to give people a starting point and keep them curious. If you can keep their interest peaked they will return and learn more.

Remember you commit code changes frequently with every change completion; document frequently when things change as well. You will definitely avoid those Friday marathon session.