As a professional writer, I admit that I probably focus on documentation more than your average software developer. Over the years, I have learned quite a bit about what goes into making a GREAT system document. I have also noted the extreme lack of good quality system documentation at many of my client locations.
Unfortunately, next to initial design and testing, documentation probably comes in last as far as the amount of time allocated to it for development projects. I have met plenty of programmers who think that the only documentation they have to provide is the occasional comment in their code. By the time the project is over, very few people take the time to go back and create a proper system document.
What most novice programmers fail to realize is that good system documentation is not just a benefit for the client or even for other programmers. It is also not just for large or commercially-based projects. A system document should be created for any size software development project, whether that be for a commercial-based project or just a single-man project done in a small IT department.
Why Bother?
If done properly, a system document can serve many purposes – most of them benefiting the person that created the document. I have been creating system documents for all my software projects for the past 20 years and I have benefited in the following ways:
- A GREAT system document serves as a calling card for you. It demonstrates that you are a quality worker and that you are attentive to detail. It also reminds people about the work you have done long after you have left a place. This is especially important for software consultants. I actually had a former boss recently contact me for a consulting job, all because he ran across a system document I produced 10 years ago.
- You can refer to some of your best ones when trying to land a new job or consulting gig. Unless you work exclusively with public facing web sites, it is not always easy to provide a direct link to some of your past work.
If you keep copies of all the system documents you have produced for employers or clients, you can use these as examples of your quality work. I can promise that offering or producing them for an employer WILL set you apart from the rest of the developers.
- It can save you LOTS of time. I cannot tell you how many times I have gone back to reference system documentation I have wrote for one project when working on another. In many cases, the stuff I read (even just 6 months later) seems entirely brand new to me and is often very helpful in pointing me in the right direction for resolving a problem or coming up with a good idea.
What Should it Contain? 
After years of creating system documents, I have learned a thing or two about what works best. For example, simple and straight to the point language is the best. It should NOT read like a White Paper or some graduate student thesis. It should not even resemble professional software documentation.
If you are creating a system document for a project that involves using some other piece of software, do not include information that could be found in the manual for that software. For example, I created a system document for a large integration project that I worked on. The project involved using a software tool called Scribe to create data transformation scripts. Scribe already has extensive documentation that covers how to use that product. There was no need to include any of that. In fact, my document included a section that stated this fact and pointed the reader to where the online Scribe documentation was located.
The system document you create should contain the kind of information that is not obvious. Get to the point and stick to only including things that someone like you, someone who knows the project intimately would know. The exact length of the document will vary depending on the complexity of the project.
Your document should always include a Last Updated area in the header. This should include a date time that is updated automatically when the document is opened and saved.
As far as what sections to include, I suggest some of the following:
- What is this about?
This section is required and should be the first section in every system document you produce. It should contain information about who originated the project and provide some reasoning for why it was done. The system may be multifaceted and involve multiple applications and scripts, so all of these pieces should be referenced in this section. - How do I use or access it?
This should provide a basic overview of how to use or access the system. If the application is web-based, it should contain a link to it. If it is a desktop or console application, it should specify where the installation files are located. It should also include any special logins and passwords that may be needed.It should assume the reader knows nothing about the system and they are just getting started using it. Including screenshots of the application can be very helpful. This should not be as extensive as a complete user document, but it should at least get the reader logged in to the system and familiar with the basic layout. - How do I get started supporting or modifying it?
This should contain information that a software developer would need to know to access the system as quickly as possible. If the system consists of more than one application, then it should contain links or paths to where the code is located for all applications. If working with the software involves installing any other special software, it should include information about that and what is needed. - What if it does not work right?
Hopefully, the person creating this document has kept notes while working with the system and has undoubtedly encountered issues while testing and deploying. These notes will be helpful in building this section, which should be a bulleted listing of what these issues are and what can be done to resolve them. Remember, the reader of this document is someone who will be tasked with supporting the system and they will likely not be familiar with all the problems you faced creating the system. - What kind of changes will I need to make to the system?
Ask yourself what kinds of changes will likely need to be made to the system and use this section to list those areas. For example, what if the system needs to be moved to different servers? What if the person supporting the application needs to change configuration or database settings?
When should it be created and how much time will it take?
Ideally, you should allocate time in every software project for creating system documentation. The amount of time you allocate is proportional to the size of the project and in my experience is usually about 10% of the total project time. So, if a project takes 100 man hours to design, code, test and deploy, 10 hours should be allocated to creating system documentation.
NOTE that this is separate from any user documentation that you may have to create. The time required to produce user documentation should be included in the total project time. The reader of the system document is someone who will be tasked with supporting or modifying the application. They are likely a software developer and you should assume that they are brand new to the organization.
I understand that creating system documentation like this is not something that comes natural to most developers. But, I can promise that the more you do it, the easier it gets. And, I can also promise you that if you take the time to do it right, you will thank yourself for doing it one day.
saramorgan.net 