• 91997200
  • enquiry@oasiswebasia.com

Blog

Does your web developer do technical documentation?
25 Jan

Does your web developer do technical documentation?

Posted by

It is common for SME company like you to face a major problem when your web development vendor decided to stop their services or when your senior IT manager decided to call it quit. We are going to find out what we can do to cushion the impact of this fallout by getting these things done first.

What is Documentation Process?

Basically, the task of the documentation process is to assist web developers in getting accustomed to the functional aspect of coding. It is all about how they work and deliver effective results. In fact, it is like a thin material that should not be avoided by the developers.

Types of Documentation

 

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.

 

Summary - Include technical documentation as part of your contract

Team Oasis recommends that you discuss with your project manager before the start of the project. Your project manager must be able to relate your requirements to business rules documentation.

In the case that the project manager is unable to perform, it is an indicator that your web developer might not be able to understand your business requirement and resulting in poor development. This often happens when it is the salesperson who closed you on the project and pass it to a project manager who just forwarded the information provided by the company and expect the web developer to plan, design, and develop the website with great quality.

This will result in paying an additional large sum of money to the next web agency as they are unable to reuse any of your codes without documentation. Web agency will charge a bigger fee for discovery on your existing website and this can be prevented. It is ideal to consult the senior web consultant in the agency to know how your project will be developed.

With documentation, you can easily scale your web development with multiple vendors easily or to be able at least handover your website to your next web development agency without much hassle.

Looking for a Proven Web Development Strategy?

About

Oasis Web Asia is a Singapore-based web design and web development company.

We provide website design, website development, e-commerce solution, content management system (CMS) solution and hosting services for all businesses.