Year Of Security for Java – Week 51 – Document Everything

No Gravatar

What is it and why should I care?
As I mentioned last week, this series is comming to a close. I also said that I have two concepts that I find myself sharing more than any others. The first I shared last week was to – Think.

This week I’ll briefly cover the second topic … “Document Everything”.

Again, this is a simple thing, but it is usually not done, especially by programmers. There are exceptions to the rule, but programmers are stereotypically bad at documentation. We generally either a) don’t do it or b) do it once and never update it. The example I usually go to is – think about some of the better-documented open source projects you’ve used (spring, grails, bootstrap), and then think of some others that have poor documentation (won’t name them :>). Consider which ones you generally enjoy working with more and how much of a role documentation has to play in that. Also, think about how long it took you to come up to speed on those frameworks and how long it might take you to refresh version changes, etc. Documentation can make all the difference in usability and desirability of a product.

What should I do about it?

Documentation has a reputation for requiring huge amounts of time and effort. Depending on what you are doing, that might be true. However, in practice, you can ease those burdens quite a bit if you follow a few simple steps:

1. Document as you go.
If you are writing comments for code, add them before coding or inline while you’re writing the code. Don’t commit the code without comments. If you’re writing to produce end-user or other more formal documentation, write as you do the design, or while working on the component you need to capture documentation for. The process of writing will help you clarify issues in your mind as well as root out areas of uncertainty that you might have not considered before.

2. Write as simply and clearly as possible.
Don’t add fluff. Write down the steps that are necessary and stop. Over time, you may expand your documentation, but don’t start with lots of documentation that is unnecessary, especially since it’s more to maintain over time.

3. Get a good proofreader.
A good proofreader is invaluable for documentation. Your editor will help you with some dumb mistakes, but your proofreader will catch others. Much more than that, your proofreader will likely think a little bit differently from you and help you find areas of your documentation where you might have implicit assumptions or unclear statements and help point you to areas that need work. Try to team up with someone else who is writing and trade proofreading tasks – reading for others will also make you a better writer.

4. Update your documentation on a regular basis.
Stale documentation is often worse than no documentation, because it’s misleading to those who are trying to use it. You may be actively giving out false information. It’s a good idea to consider what level of freshness your documentation needs, and then set calendar reminders to review and update the documentation on a periodic basis.

As long as you follow these basic steps, you’ll have a good start on producing solid documentation, and you will improve over time.

Documentation is a powerful tool. The reason I started this blog was actually because I needed to document programming concepts that took me some time to figure out and I wanted to remember them and not have to re-learn them. Over time, folks started finding the site and letting me know that they found them helpful as well and requested I write on different topics. Some of these requests came from co-workers and others came from strangers on the Internet. That was the genesis of this series, in fact – writing down what is essentially an FAQ from folks over the years about various topics related to Java security.

In conclusion, there are two mantras I repeat to folks constantly – think and document everything. Thinking means you should be coming up with the right (or at least better considered) solutions and documenting them means you are preserving both the solution as well as your discrete thoughts for posterity. By using these in tandem, you should be able to perform at a higher level, and share your work in a more meaningful way.

Be Sociable, Share!

Technorati Tags: ,