It’s a situation that is very familiar to the software development community: an organization is supporting an antiquated application backed by an aging codebase, and a developer new to the team is tasked with completing a programming task within this codebase.
How to build better support and understanding around your company's proprietary codebase. Download now (pdf)
The problem is that the documentation for this application (if it exists) is typically sparse, out-dated, and scattered across various platforms. In addition, the original developers who wrote the code may be too busy to assist the new engineer or may even have left the organization. For developers trying to adequately familiarize themselves with an aging codebase as they attempt to complete support tasks, such challenges often create confusion, which leads to a steep learning curve.
So how can an organization handle this situation in a manner that reduces the learning curve for those supporting aging codebases? The challenges of producing and maintaining effective documentation for aging codebases are discussed below. We’ll also cover the types of information that teams should document in order to ensure that new team members have all they need to get up and running with an aging codebase with fewer pain points and a smaller learning curve.
The Dangers of Employing Non-Standard Practices for Familiarizing Developers with Aging Applications
Let’s be honest, very few developers enjoy writing documentation. It is often considered to be an unfortunate collateral responsibility of the position. However, documentation is crucial to consistently supporting an application, and non-standard processes for passing knowledge from one individual to another create several challenges down the line.
The Drawbacks of Ad-hoc Person-to-Person Knowledge Sharing
Not to sound anti-social, but a developer needs to avoid relying on face-to-face interactions when getting up-and-running with an aging codebase. Various liabilities that exist when knowledge is shared face-to-face or through impromptu discussions via email or a messaging client. Here’s why:
- Face-to-face conversations do not live on. Information shared in-person cannot be referenced later. Consequently, the same discussion is repeated to retrieve the same information. This is obviously impractical. The information should be made available in a manner that doesn’t disturb developers trying to keep up with other responsibilities.
- While sharing knowledge through email or instant messaging makes the information available in a digital format that can be referred to later and shared with others, emails and instant messages are often lost. Clearing an inbox or deleting old conversations is common practice. Searching for one specific comment in an email or old IM conversation can be a tedious process. That and the fact that this information may only be available to those involved in the initial discussion rather than to the team as a whole further reduces the efficacy of this approach.
- Team members do not often stay with one organization for their entire career, and when a team member with critical knowledge leaves for another opportunity, it is unwise to allow critical information to leave with them.
In short, new developers often need to support aging codebases when those who developed the systems are busy with other development tasks or have since left the organization. The knowledge gained during the development of the product needs to be preserved so that future developers providing support for the aging product can reference it.
Identifying Information that will Reduce the Learning Curve
So, what types of information should be considered critical for a development team to document? Keeping in mind that the goal is to reduce the learning curve for new developers, you should maintain up-to-date documentation on the following:
Local Environment Set Up
What does the developer need to do to get their local environment set up? Software engineers are a logical and intelligent breed. As developers follow the steps to get their local environments running, they will be learning more about key aspects of the application, such as which frameworks were used to develop the application, as well as which internal projects the application utilizes as dependencies. If not, then those dependencies should be documented as well. Few things are more frustrating to a software developer than having to troubleshoot the initial setup of an application before they can even get started digging into the code itself.
Application Requirements
Application requirements can be complex and difficult to sift through for a developer who is new to supporting a particular product. In addition, they tend to evolve as new versions of a product are developed. Maintaining up-to-date documentation on all application requirements will help decrease the probability that new personnel will ask how a particular feature should be working when pulling a codebase for support tasks.
A Picture is Worth a Thousand Words: Data Flow Diagrams and Entity-Relationship Diagrams
Reading through code, while critical in its own right, should not be the only way developers familiarize themselves with the inner workings of an application. Diagrams can provide clarity regarding application design. Data flow diagrams, for instance, provide a graphical representation of how information moves and changes through a system and can allow a software engineer to see the big picture when attempting to understand the processing that occurs within an old application. For instance, when working on a sales system developed years ago, it helps to know which statuses an order can be associated with and how the status of an order is modified as the circumstances surrounding an order change. Reading lines of code describing a process such as this would be very tedious compared to seeing context provided by a pictorial representation.
Entity-relationship diagrams are another valuable form of documentation for software developers who wish to acquaint themselves with an aging system. Diagrams of an application’s database design (what information is stored where, how records in one table relate to those in another, etc.) provides developers with context that is crucial for understanding what is happening when reading through existing code.
Getting the Right Information Quickly, Easily and Repeatedly
In order to reduce the learning curve that comes with supporting existing codebases, developers need to be provided with the right knowledge quickly, intuitively, and in a repeatable manner. Here are a few tips for managing information that has these qualities:
- Developers should know where to look to acquire the information that they need. You should utilize a knowledge management system (such as that provided by Stack Overflow) and train your team to leverage it so that they can both find information and document their applications going forward.
- Out-of-date documentation is only a little better than having no documentation at all. As systems evolve, make sure that your documentation evolves with them.
- When it comes to dealing with an aging codebase, providing information relevant to reducing the learning curve is the responsibility of the entire team. As developers new to the team get oriented to the codebase, they should be filling in the gaps in documentation. In other words, they should be documenting solutions for any challenges or issues they come across in an effort to make the process easier for those that come after them.
A Potential Knowledge-Management Solution from Stack Overflow
There are many knowledge-management solutions out there, and Stack Overflow offers an excellent option. As you probably already know, Stack Overflow is a community that many developers utilize on a daily basis to find answers for both common and uncommon questions related to software development.
The Stack Overflow for Teams product leverages the power of their popular question-and-answer platform for private use by internal software development teams. Through the traditional functionality found on Stack Overflow (think tagging and upvoting) along with an intuitive Q&A design, internal members can type in questions related to the specific products that they are working on and quickly find the highest-rated answers provided by others within their organization. Essentially, Stack Overflow for Teams makes internal knowledge shareable only amongst team members, allowing organizations to use Stack Overflow to privately document and disseminate knowledge regarding their own software products.
See how Stack Overflow for Teams can transform collaboration within your organization. Learn more