Documentation: Critical Business Applications.
Conducting my spot checks in many companies around, I discovered that some locally developed applications have little or no documentations at all. Yet, these “orphans” are critical to business for enhancement of financial, production, procurement, safety, logistics etc processes. These old apps were either developed by ex-staff of IT departments who have moved on or vendors who have their contract terminated. Yet, no building is erected without approved survey plan, architectural drawings etc.
In this blog-post, I will try to highlight few things on software documentation: First of all, I am aware that we all have some gurus in our offices that are good in programing. These guys are so good, they can automate anything. But when it comes to critical business applications; the standard is key. The standardized and structural approach to software development to ensure its correctness; efficiency and security will be briefly looked at in this post. I will not be able to write in this post the embarrassments that lack of documentation had cause the businesses I surveyed.
From our knowledge of Software Development Life Cycle SDLC, we have, (1) Requirement gathering, (2) Design, (3) Development, (4) Testing, (5) Deployment. Whether you use Waterfall or Agile methodology, you should never skip documentation alongside. Don’t postpone it till the end of the project as people usually do. Many a times we don’t realize the risk we are running skipping documentation until the reality comes upon us before we discover things that were left undone.
In requirement gathering, we have two types of requirements namely functional and non-functional requirements. Functional requirement describes what we need the software to do while non-functional describes the process by which it’s done. Standard software development will require both High and Low-Level Design Documents (HLDD and LLDD)
Business Requirements Document (BRD):
BRD is a formal contract between the developer and the process owner detailing the scope which includes the constraint and the restrictions. Signed
Technical Design Document TDD:
TDD is the blueprint for the application developers to use in the development of the required applications. It specifies what needs to be implemented and also how it will be implemented.
Functional Requirement Specification FRS:
FRS Describes apps intended capabilities, appearance, interactions with users. It is read by analysts, developers, PM and Testers.
System Designed Document SDD:
SDD Describes the system requirements, operating environment, system and subsystem architecture, files and database design, input formats, output layouts, interfaces, detailed design, processing logic, and external interfaces.
Flowchart: A flowchart is a picture of the separate steps of a process in sequential order that represents an algorithm, workflow or process, showing the steps as boxes of various kinds, and their order by connecting them with arrows.
User Manual: This document is written in a simple understandable style for end-user, system administrators and support staff. This will ensure self service as long as it is written in the language of the user. It will show the dos and don’t s that will ensure optimal performance of the application.
Some benefits of documentation:
Troubleshooting becomes easy. You will be sure that the app is compliant with standard application audit regulations, user requirements, with contractual business owner requirements. So also, you will have clarity of purpose of the app and not waste time to develop duplicate application doing the same thing. You will also reduce abuse, misuse, waste and fraud among others. Employees go and come but your business should stay with all the assets including business applications with documentation.
Although, tech-writing involves some level of technicalities, but it is better to check our apps and make sure that they comply with today’s standard. Otherwise, we need to draw a road map to their retirement and replacement before they retire the business unexpectedly. It is better to be safe than sorry.