5 Reasons To Have A Documentation Strategy

Documentation is one of those tasks where is very hard to calculate the ROI (return on investment). How can you know how much money you are saving by having good documentation if you do not have an un-documented version of the same project. In the same way, how are you going to compare the time you are saving by not documenting your projects if you have not documented your project and see how long it took.

No, I am not proposing you implement your projects twice, once documented and once undocumented to be able to compare. But the truth is, we do not think too much about documentation until we need it, and by then, it is way too late. So just in case we need it, let's implement a documentation strategy.

First and foremost let me explain that I am not talking about the help files you should write for your application users. This task is better left in the hands of professionals; your tech-pubs department. Your documentation strategy is for the code that goes into your application. This is a more technical documentation, and should be written by the same experts that write the code.

I haven't convinced you yet? Well, let me give you the reasons why you should have a strategy to document your code, and let's see what happens.

1. Complexity Is Best Explained In Plain Language

Despite all the post and articles you read before about how good code is self documenting, how good programmers are able to read and understand code like if it was their first language, and how a clear use of patterns will help you to understand the design and architecture of your application. The truth is that, with the exception of a very small elite group of programmers to which I do not belong, most programmers understand plain language better than any code.

Can a programmer with the right experience go through hundreds or thousands of lines of code and understand what they are doing? Sure he can. But, it is going to take him a lot longer than if he had a few UML class diagrams and some HTML help files describing the API's and their use.

"Wait a minute. Are you proposing to use UML?" Not really, but there are things that are better expressed in a diagram than in plain words (you know, a picture is worth a thousand words).

2. There Are Things Code Cannot Express

Customization points for classes; assumptions being made; side effects. These are all examples of things that cannot be expressed just with code. There are many more, and they will play a very important role once your code moves to maintenance mode.

You might be thinking, "that is what comments are for." Maybe, comments are your documentation strategy. If so, you should define it and make sure everyone understands it, so comments are actually added to the code.

Documentation and code can get out of synch if they are not maintained. Your team must understand the importance of having up-to-date documentation and make sure pertinent changes are made to it when the code changes.

3. Documentation As Training Material

Once in a while, you are forced to hire a less experienced developer, and you will be glad you have good documentation to get him up-to-speed. As he glances through the documentation, he might learn a few tricks that will allow him to become a better programmer. He can still learn a lot looking at code, but documentation is a supplement that can make his life and yours, easier.

New developers usually need some kind of Mentor that guides them through the learning process. You can save many mentoring hours if you have good documentation, and everyone will be more productive.

4. Finding What You Are Looking For

How many times have you implemented some functionality just to discover a few days later that someone had already written the same thing years ago? Undocumented code silently leads to duplication because in medium and big size teams, it is impossible that everyone knows about every single line of code written by other members.

There are many tools out there that will generate automatic documentation in a way that is easy to search and find exactly what you are looking for. This is a big time saver and promotes code reusability.

5. Because We All Forget And We Should Forget

No matter how many items you can keep in your memory (and I am not talking about RAM), sooner or later you will forget how a particular feature you wrote works. It is inevitable. If you did a good job writing the code, things will come back as you look at it, but most of the time, you will be glad you documented it.

There are times when you really want to forget. We all have code we wrote in the past that we do not want to remember. If you don't, most likely it means you have not learned much lately. In my experience, a developer presented with the exact same set of requirements at two different points in time will come out with two completely different solutions. Developers evolve and learn new things that makes them improve. This will drive them to solve the same problem in different ways.

Remember the assumptions I talked about in point two? These will also affect the outcome of the solution. Because we know now what we did not know then, we probably make different assumptions, and many times this will prevent us from understanding what we did in the past unless we have something to refresh our minds: documentation.

Conclusion

Documenting code is not fun. Maintaining documentation is a nightmare. You should plan your documentation strategy before starting a new project, so you can write the documentation from the beginning.

Your documentation strategy should be part of your code writing process. Merging both things together will make it less painful. Select a strategy that is accessible from the source code, find the right tools for you, and make sure everyone understand the importance of this task.

Documentation can bring new members up-to-speed; it can help you to refresh your mind when you need it; and it will prevent you from making the same mistakes over and over. It removes code duplication by exposing existing functionality to your development team, and it will help you to express the concepts that are hard to find and understand by just simply looking at the source code.

6 Areas To Think About Source Code Management

It has been a while since my last post. I took some vacation from work to be able to spend time with my family during the holidays, and they have taken all my time. Now, I am back to work and back to post, and I will continue where I left.

I finished the year talking about seven strategies we should define before starting a software development project. In this and subsequent posts, I will give you the reasons why you should plan ahead and implement those strategies. I will not talk about specific processes or tools. You should evaluate what fits your current situation, but I will point out the things you should think about and what the relevance is for each of the strategies.

Since the first strategy I mentioned was Source Control Management, I will begin the series explaining the areas you should think about when you implement a Source Control Management strategy. I know, you are already using a Source Control Management System (SCM), but an SCM is a tool, and we are not talking about tools. Do you have a strategy on how to use your SCM? Does everyone in your team understand and agrees with your strategy? Your answer might be yes, but keep reading, you might find a couple of things you have not think about.

1. Managing Source Code Changes

If there is something you can be sure about any project is there are going to be changes. In software development, changes in a project usually translate to source code changes. Your Source Code Management strategy should establish how changes are made, and who is allowed to make the changes.

This seems very simple, and for the most part it is. However, there are certain times when things get a little bit tricky, and your strategy should define what needs to happen when things are not as straight forward as usual.

Source code changes might break the build or destabilize a feature. When that happens, you may choose to allow developers to keep submitting changes and hope for the best, or you may opt to lock your SCM database until a fix is found. Maybe, you decide on an option that lies somewhere in between. You may want to evaluate the situation and make a decision based on feedback from your build process, your development team, or the QA team.

Everything is good as long as your strategy defines what the procedure should be, your policies are consistent, and everyone buys into it. Otherwise, you will be making the decision when problems arrive, pressured by the current state of affairs, and with little understanding of the true impact of your decision.

Furthermore, the next time you run into a similar situation, you will second-guess your previous choices, and you will be tempted to handle things different. This will cause enormous confusion in your team and will increase the chances of someone making further mistakes.

You should plan for these situations, and your strategy should define how they will be handled. Allow your team to participate in the design of your strategy and listen how certain policies will impact their work, but always keep in mind that your source code and the stability of the product should come first.

2. Documenting Changes

We all know source code is going to change, but there is always a reason that triggers the change. We might be adding features, removing features, or fixing defects. Whatever the reason is, we, most likely, will forget about it in a few days.

Our Source Code Management strategy should define how we are going to document changes, so we can go back and review and understand what triggered certain change, how was implemented, and which source files were touched.

You may decide to use submission notes stored in your SCM or send an e-mail message to the entire team when a change is submitted. You may want to get fancy and create an RSS feed your team can subscribe to and receive the latest information about the on going changes to the project. Whatever you do, you need to define how changes will be documented.

I cannot tell you how many hours I wasted researching a problem going through useless submission notes because there was not a establish procedure on how to properly document a change. Most developers are very proud of their work and will spend as much time as needed documenting the changes they make. Most of the time. Until, they have to fix a critical bug the day after the application was released to create a hot-fix for an important customer.

During hectic times, good developers forget about many things, and the easiest thing to forget is to properly document changes because "in theory" it will not impact the end result. However, a few weeks after we release our hot-fix a new problem is found, we review the latest submission notes, and we cannot seem to find what might have caused the problem.

Evangelize about the importance of properly documenting changes. Create a standard template or form that will help your team to properly document submissions. Make it easy for everyone to document changes so your team can see the value.

3. Parallel Development

In any software development team bigger than, say... one developer, development occurs in parallel. Your team might be working on different features at once, work on new features might be done in parallel with the stabilization of completed features, or a team is working on the back-end of a feature at the same time as the UI layer. Parallelism is necessary to implement features quicker and more effectively.

What this really means is that changes in the source code are coming from every direction, and your Source Code Management strategy should plan for that. The bigger the changes are, like adding new features, the bigger the impact on the stability of a project.

You may decide to create separate branches for new features; you may decide all development should go to the same main branch. That is up to you to decide, but make sure your decision fits your needs and that everyone is clear on what the protocol is.

If you are using several branches for your parallel development, you must define how changes will be propagated between branches, who will be responsible for the integrations, and the exact procedure to perform a correct integration. You want to keep all active branches as close as possible to minimize integration problems. Your strategy should define under which circumstances a new branch should be created and when the branch will be considered closed for development.

Provide your team with guidelines that will help them stay as close as possible to the latest revision of the project. Ideally, they should stay as close as possible to the latest successful and stable build to minimize the impact of a bad submission on their work.

Invest on training. Provide your team with the necessary training on the SCM tools you use and make sure everyone understands and follows your strategy. Listen to your team on the policies that get on their way and make appropriate changes.

4. Rolling-Back Changes

So far, I have been talking about what you should consider and define when introducing changes in your source code. But most of the time, we forget to think about how we are going to roll-back a change that we made and is no longer necessary or caused more problems than it solved.

Your Source Code Management strategy should define how changes will be reverted. This is a tricky operation because sometimes it is hard to know what the status will be or should be after we perform the roll-back. We should define a set of guidelines that will help performing this operation in a successful way, at least, most of the time.

Everyone in your team should know how to roll-back a change they made. Provide them with the necessary training to perform this kind of operations. Make sure they understand how the tools work, and they feel comfortable using them.

5. Going Back In Time

Just thinking about it gives me the chills. All of the sudden, someone thinks is a good idea to fix a problem in an old version of your software, and you need to go back in time, get the snapshot of your project from years ago, make the necessary changes, and release a patch for an older version of your product.

Well, if your Source Control Management strategy has not planned for that, you are probably going bananas right now. You might get lucky and a simple "sorry, we cannot do that" will deviate the attention to more important tasks like getting the next release out the door. Sometimes, luck is not on your side, and your favorite sales person has already promise the fix to an important customer who cannot wait for your next release which contains the fix.

You should be able to go back to any point in time (or at least any important point in time), and retrieve the exact snapshot of your application back then. Probably, this is not the only thing you need to do, but it is a good start. If you have not defined a strategy that allows this kind of operation and proved that it will work, the chances of success are zero, null, none.

Always consider the most extreme cases and plan for them. They probably never happen, but when they do, you will be glad you have a plan.

6. Natural Disasters

Last, but not least, your Source Code Management strategy should define the policies by which your source code will be kept safe under any circumstances. Hard-drives crash, servers go down, and once in a while Mother Nature plays a trick on us.

It is your responsibility to define a back-up strategy, but most important, it is to define a restore strategy that you know it works. You can have all the back-ups in the world, but if you are not able to restore from them, they are basically useless.

Things can go terribly wrong. When that happens, we feel the pressure on our shoulders, we cannot think clearly, and it seems the world is about to end. It is not the best time to think. If we have a plan, we stick to the plan. Hopefully, we also tested the plan before we put it into practice, and we are comfortable enough it is going to work. We still feel the pressure and the adrenaline rush, but we know there is light at the other end, and it feels good.

Conclusion

The source code you produce is the most important asset you have. You have to define how you are going to manage it, and how you are going to keep it safe. A consistent strategy will help your team to follow the correct procedures under any circumstances. Your team should provide you with feedback on what is working and what is not, and you should listen and evolve your strategy to insure guidelines are improved and followed.

Needless to say that an SCM system will help you manage your source; that is what SCM systems do, but you and your team should be the ones deciding which tools are good for your situation. When you decide, make sure everyone in your team is properly trained on the tools you are using. Also, make sure they actively participate elaborating your strategy. Talk to them and do not be afraid of changing policies that are not working. People learn from experience, and it is almost impossible you will get your strategy right the first time around.