The Importance of Documentation in Software Development

Alex Trica
By Alex Trica
18 Sep at 10:02

For a programmer reliable documentation is always a must. The presence of documentation helps keep track of all aspects of an application and it improves on the quality of a software product. Its main focuses are development, maintenance and knowledge transfer to other developers. Successful documentation will make information easily accessible, provide a limited number of user entry points, help new users learn quickly, simplify the product and help cut support costs. Documentation is usually focused on the following components that make up an application: server environments, business rules, databases/files, troubleshooting, application installation and code deployment.

 

Server Environments

Detailed documentation about an application and its environments is always a must. This information will help with setting up new environments for your application and it should present the location and function of the systems that run your services. Things that should be specified here are the application name/version, server name, IP, code directory, URL to the application, operating system, user account information and a point of contact.

Business Rules

Business rules documentation help new additions to the team adapt faster to the working habits of the company. It provides information on how the product works and why. Business rules documentation can easily be supported with requirements documents if available. This will speed up a developer's learning curve significantly. In addition to business rules, a help document, FAQs, or user guide can help highlight the main points of an application for a developer who needs context for the application they are supporting.

Database/Files

Database information is mandatory for porting, reverting, sharding, migrating and so on. It is important to know the type of database, the server information, the version but most importantly to have a data model diagram. Documentation of the database will make bringing additions to the table, modifications to the structure and types, additions of indexes and keys much more simpler and easier to control/debug. Also, if an application presents a file transfer functionality, it is recommended to document which way the transfer is made, through which protocol and datatypes, if and what SSL certificates are needed.

Troubleshooting

The troubleshooting documentation helps when running into production issues. Most technical issues should have error codes that should help with troubleshooting. In this document there should also be included an FAQ section to deal with general or usual problems (such as configuration issues). The errors should be documented split by type of error, module where it comes from, and level of error (exception, warning, critical, etc...).

Application Installation

Installation and configuration documents are useful for when developers need to set up new or additional application environments. If possible, the steps should be detailed and easy to follow and can include screenshots if necessary. Anyone should be able to follow the steps and successfully install an application. Having the steps identified will help the installer prevent problems because of missing parts of an application. Details such as necessary software, libraries, and application server versions, can be included to ensure the environment will be compatible and set up as intended.

Code 

The code documentation is the backbone of every application. Code documentation can be split in multiple parts. The first one, the most helpful for programmers are the comment blocks. These will be found through every file explaining classes, methods, parameters, possible errors. Then comes the specific file documentations. These are usually generated through a third party script which will parse a file and, based on the comment blocks, will create an explicit PDF. Afterwards there should be information regarding the code repository, where the file updates are found, and where they need to be moved. In addition, there should be step-by-step instructions on how to create an application package or a build to be deployed.