As a developer, it’s always important to have reliable documentation to guide your work. If you are like most developers, you can be supporting multiple applications at the same time, which means that it is even more crucial to have documentation in place to help track all aspects of each application. It’s also helpful for development, maintenance, and knowledge transfer to other developers. The following are some areas in which documentation is especially valuable for a developer and some of my thoughts on what should be included. If possible, the documentation should be focused into the various components that make up an application.
Server Environments
It is always beneficial to have detailed documentation about an application and its environments. Having this information readily available is invaluable when setting up new environments for an application and/or maintaining existing ones for development, testing and production. This documentation should state all the information desired for each environment to include the application name/version, server name, IP, actual server location if necessary, directory path for the code, URL to access the application, operating system, user account information, and a point of contact.
Business Rules
Having a business rules document is extremely helpful for developers who need to learn how and why the application works the way it does. To get this information, a developer can also read through requirements documents if they are available. This type of knowledge comes with time spent working on an application, but if some details can be provided, it will definitely speed up the developer’s learning curve. 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
If the application has a database, it’s helpful to know the type of database, the server information as described above, the version, and if possible, the data model diagram. Applications can also have jobs that run nightly or ETL jobs that import/export data from other sources that may not be easily identified. If an application has file transfer functionality, it is good to document what server the application sends or grabs files from, user account information, and whether any SSL certificates are needed. All these types of processes can be documented to help during development and maintenance.
Troubleshooting
Having documentation also helps when troubleshooting production issues. An FAQ document can speed resolution for data issues that come up over and over with previously identified solutions or workarounds. Most technical issues have error codes that can help with troubleshooting but data errors sometimes need additional clues as to why something may not be working properly. This is another type of knowledge gained through time working on an application, but having these documented can speed up the troubleshooting process, especially for a new developer working on an ongoing project.
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 Deployment
Most companies have their own deployment processes when doing releases and code updates and it is always helpful to have the deployment instructions documented. 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.
All these documents should be readily available to the developers and team members on the project. These can be placed in a document sharing portal for easy access, access control, and version control. In order for them to be useful, they should be updated as changes are made or new enhancements and processes are added to the application. Having all the necessary documents pertaining to your application will make your development and maintenance efforts more efficient. When I started working at Segue, I was provided with documentation that helped me get up to speed on my new projects. I have also continued to use the documentation when necessary.
After years of doing development, I know that writing documentation takes time, but for developers it just needs to be functional and updatable – not necessarily pretty. If done up front, documentation will definitely save time and money in the long run.