Anyone who has been working in the I.T. industry for a few years will probably have had the conversation about documentation with peers or management, who need documentation in order to understand what the I.T. person has done. So, what are the common excuses for not providing supporting documentation?
• No one will read it.
• There’s no point creating a document. It will be out of date next week, as the software the document refers to is constantly being updated.
• Documentation is always the first requirement to get dropped in the software development lifecycle when time constraints are tight.
• Developers prefer to keep their software knowledge “hidden”, so that their jobs are safe.
No one will read it
It is a valid point that “No one will read it”, but there are also valid reasons why this is true. If a document is written without first thinking about who the target audience is, then it’s true that no one will read it. Most documentation should be written with the intention of supporting the release of software, and must be thought of as a reference document to be consulted in the future.
So here are a few tips when writing documentation:
• Keep in mind who is intended to read the document, and pitch it accordingly.
• Keep it short and concise, which will help with the excuse that nobody will read it.
• Keep it simple and use an appendix for any acronyms used.
• Include the Business Analyst or Project Manager in the review process. If they don’t understand it, no one else in the company will.
• Avoid rewriting the code in English. The documentation needs to describe the purpose of the software, i.e.; what business issue it is resolving. It does not need code. Also, that way it will never be out of date.
It will soon be out of date
A document that becomes out of date quickly can be easily avoided. How the document is structured will affect whether the document becomes out of date. A poor example of documentation structure is when blocks of software code have been cut and pasted into the document. This is, of course, a sure-fire way to ensure the document will be obsolete within the first few months of it being published. A good example would be to describe the purpose of the software the document is supporting and don’t focus on the detailed code used.
Also, it is important to think about how documents are stored and published within your organisation. If documents are stored on a server somewhere that only the I.T. System Administrator is aware of, how are other employees going to be able to retrieve the document in the future? A good way of writing and publishing documents is to use online tools such as intranet pages. These normally provide good search facilities, and also provide the ability to update existing published documentation.
Time and other constraints
Sometimes project deadlines can dictate what must be included in the project delivery and what would be "nice" to include. In this scenario, one of the first deliverables to be dropped or forgotten is documentation. Deadlines or delivery dates can be affected or even set by many internal and external constraints. For example, a Government has demanded that software be written or modified to meet certain regulatory requirements. In scenarios like this, it is impossible to move the delivery dates, and in many instances, fines are imposed on the company if the Government deadline is not met.
A developer may often feel like the person at the bottom of the food chain, in terms of the project lifecycle. They wait while the business people procrastinate on how best to tackle these external requirements. As each day passes, the development team loses a working day. Eventually when the development team gets the green light to proceed, the project is already behind schedule. Inevitably, documentation is dropped from the project to meet the imposed deadline.
However, time should be allocated by the business people to create the necessary supporting documentation after the project was initially delivered. Staged deliverables or a second phase of the project should be used to ensure this happens. More often than not, the next “urgent” project is in the queue, and as a result, this post-project necessity is often forgotten.
A well-kept secret?
Developers sometimes avoid providing documentation alongside the software they have created. They see this as a tactical move to ensure the knowledge of how the software works is kept hidden, which in turn can ensure their job is kept safe.
However, there are benefits from both a permanent and short-term contractor perspective to writing these documents. A permanent employee can raise his or her profile within the company, as the author of this documentation which is used by many others within the company to resolve queries or issues. The author can be regarded as a proactive, productive employee and as someone that can be counted on in times of need.
One of the objectives of a short-term contractor is to get that contract extension or a future renewal. A great way to show a client (or employer) that one is committed to providing a high level of service is to provide a complete work package. Good quality documentation that comes with the software is a great way to enhance one's profile within a company, even if one has only been working there for 3 to 6 months. Even after the contract is finished and the contractor has left the company, employees will still be reading that documentation to help resolve issues. So, to any developers out there, make sure that you have stamped your name and contact details on the first page of any documentation you create.
Yes, there are times when it’s tough to get the time to create good quality documentation as part of the software development lifecycle. But documentation should not be ignored or forgotten about. Both the company and the employee can gain from the process. For a little extra effort you can get a lot back in return.
Photo credit : Photos Libres
By not documenting the work don't they risk duplicating the work of someone else? How do you keep track of what others have done if there is no documentation?
You are definitively à coder and a writer! Thank you for this well structured and interesting article about the IT world. I am one of those who appreciate a clear documentation to refer to instead of always asking the IT for a solution.