I have read quite a few blog posts over the last few weeks on documentation. Some of the posts are specific to SQL Server, some are more general in their approach choosing to explain why documentation is good practice and indeed necessary, why it is not just important to have documentation, but to have good documentation. There are also those that try to explain why people choose not to do documentation. They are all good posts in their own right, but only a few of the posts I have read take a moment to actually detail HOW they go about creating (& maintaining) their documentation.
People will find excuses (I have been one of them) not to do their documentation – on whatever subject/system/process/application. These may be:
- I don’t have the time.
- It’s not my responsibility.
- I am not a technical writer.
- Where do I begin?
Whilst I am sure that there are organisations that have numerous procedures in place for rigorous documentation of systems & processes, coding standards & conventions, there are (I am sure) many many more (smaller) organisations that have little or no documentation. At the very least, it’s a collection of random text files, word docs, Visio diagrams placed in any number of directories. Most of the knowledge of the way things work is stored in a few key employees heads. Whilst this may seem like a position of power to the employee (they’re ‘irreplaceable’), the organisation is taking a huge risk. As an asides, someone once told me “If you can’t be replaced, you can’t be promoted”. It is worth remembering.
Excuse #1 I don’t have the time.
More than likely, this is a cover-up for Excuse #4. There is always pressure to get projects finished as soon as possible, and that means the solution needs to go into production yesterday. Documentation is sometimes relegated to a date beyond that of the ‘go live’ deadline. And then as soon as you begin putting ‘pen to paper’ on the handover documents a new project comes along and documentation, once again, becomes a dim-and-distant memory.
Excuse #2 It’s not my responsibility
Oh yes it is. Trust me, if you ever want a holiday where you are not on call, it’s your responsibility to ensure that whoever is to hold down the fort, has the information they need to do so. Hands up all those who have accrued two years’ worth of leave because they were the only ones capable of maintaining their systems? I have known several colleagues who were in this position.
If you are building or administrating a system, you are responsible for imparting that knowledge to others. How you do this is another matter entirely.
Excuse #3 I am not a technical writer
This doesn’t matter. Whilst it is important to have good documentation, it is better to have something rather than nothing. If your organisation is yet to standardize documentation practices, this is your chance to take the initiative and show what you are worth.
Excuse # 4 Where do I begin?
I am willing to wager that this is the category that a lot of people will fall into. What needs to be included in the documentation? What level of detail is required? Who is the target audience? There are so many questions. As a developer/DBA/sysadmin it can be difficult to imagine what it is other people need to know in order to accomplish certain tasks. Assumptions are made, and then it all goes terribly wrong.
What am I getting at?
I believe that all of the excuses outlined above can be dropped if it was easier to create documentation. This focuses on the How. I have searched high and low for templates that can be used for a number of things, ranging from Database dictionaries & descriptions, system processes and procedures, development standards & conventions, reporting services templates/design standards, integration services standards & consolidation, the list goes on. I have had to settle with creating my own, and they always being improved, but by no means are they perfect.
How many of you would complete documentation if it were a matter of checking boxes and filling in blanks? If you had a template for, say, technical details of an integration services package, I am sure that you would be more inclined to fill it in and therefore share the knowledge of that particular solution.
I am asking the community to collaborate, in whatever your speciality is, to share your documentation methods, templates, best practices. I would like to start a wiki of sorts that provides this information to everyone. Something that can grow from the community, for the community.
If you are interested in helping to get this started, email me, Tweet about it, DM me, or simply leave a comment. I am certain this could be a huge resource and one that would ultimately assist many people/organisations to centralise their knowledge base.
Some links to other posts on documentation:
