I’ve been building websites since 2002. As WordPress and other platforms have evolved, many businesses take their websites into the “Application Design” realm. These are websites where WordPress (or some other platform) is the starting point for programmers to implement custom code that transforms the website into a web application specific to particular business needs. Then the programmer goes out of business or gets another job, and there is no one around to keep the website maintained as WordPress and its components release new versions, causing something to break. 

I get a phone call asking for help. I request the programmer’s documentation about how their system works so I can figure out how to maintain the website or get another programmer involved (I’m not a programmer), only to learn there is no such documentation. That’s when the real money starts coming in for my company. 

Without documentation, everything has to be reverse-engineered. A clone of the website has to be created and protected from the public while the website is probed and prodded to figure out how things were put together by the previous programmer. Then, before a corrective action can be known, the system has to be documented, and that documentation reviewed to make sure it is complete. The act of documentation is also an act of discovery, whereby the corrective action becomes clear only once the system is fully understood. At this point, the client has paid for discovery, not remediation. It can run into the thousands of dollars, and the website is still broken. 

Once the appropriate corrective action is revealed through documentation, that action is taken on the clone and tested. Problems are noted, and the coding revised. This process continues on the clone until the client confirms the situation is resolved. Now we repeat the entire process on the live website until the website is finally back in top form. I’ve seen this take over six months in some cases.

The cost to businesses from programmers that have no inclination to document their work is difficult to assess. Still, in my own small business, I’ve seen it run well above 10K in certain situations. Exasperated clients who thought their web application was a stable and unchanging thing learn for the first time why things break with WordPress. Nobody has told them that WordPress is an evolving environment where the core of the system and its plugins and themes release new versions almost monthly. They usually have not been told that such updates can break the website, and that they should have had a maintenance strategy all along to avoid the cost they just paid for.

So, what does good documentation look like for a custom web application built with WordPress? It looks the same as any other developer documentation for software, regardless of if it’s a website, a mobile phone app, or an Intranet app inside a government silo. It is geared toward developers, not the office manager, and it provides the following answers:

• The use case requirements that the code is designed to fulfill. These are usually business rules the client has created for the programmer to follow.
• All dependencies the code creates. This includes other code bases such as WordPress plugins and themes, or other modules of code that the system relies on.
• The version of PHP it will work on. Right now version 7.4 and version 8.2 are the standard, with 8.2 being the more secure PHP code base.
• The ideal workflow from step one to the end, in a bullet list format or a flowchart.
• Warnings about critical weaknesses or security concerns. Every code base has such concerns. It’s not unusual. Knowing these safety issues allows countermeasures to be taken.

Dead Components Can Wreak Havoc

I work primarily in WordPress but also build using Squareup.com, SquareSpace.com, and Shopify.com. All of these are considered Content Management System environments, but only WordPress requires you to keep the code base current and running smoothly yourself. All of these systems can be expanded using components called plugins or by injecting custom code in some way. A common approach among developers is to augment an existing plugin or set of plugins with custom code that results in the desired outcome based on the use case requirements. This can save a lot of money because instead of having to write code that does everything the plugin does, plus augment that code in the desired manner, the plugin instantly provides most of what is needed and usually has annual licensing costs under $500.00. It could cost tens of thousands of dollars to create the environment the plugin provides, so in this way money is saved. However, this is also where a lot of money can be lost.

Consider the common case of a WordPress website using a plugin that a programmer has augmented with some custom code in order to get the desired outcome. What happens if its authors abandon that plugin? At first, nothing. The plugin continues to work. As new versions of WordPress are released the danger that the plugin will stop working increases because updated versions of the plugin are no longer available. Long before that day, however, the plugin’s lack of an update usually causes it to become a security risk. Now, we have a plugin that is critical but which cannot be trusted. There are only two options available in such a situation: 1) Pay a programmer to recreate the needed plugin functionality in a manner that is secure and will not suffer from updates; 2) Hunt around for another plugin and then pay the programmer to re-code everything to use the new plugin. Either way, it’s unlikely the situation gets resolved for less than $10K. 

Now let’s take the very real-world experience I have seen play out first hand in situations like these. Let’s say a company goes through all this expense to right the ship, but the programmer offers no documentation and then goes out of business. Guess what? More costs. Because now, in order to get another developer involved, the entire thing will have to be cloned and reverse-engineered, as I mentioned at the beginning of the article. Large companies may be able to absorb these costs, but they can be devastating for a small to mid-size business relying on their website to perform critical business functions.

Documentation Is A Survival Mechanism

In the world of software, documentation is oxygen. As you’ve seen by now, deciding to forego paying a developer to produce documentation can be an expensive way to save money. The biggest objection I find some developers use for documenting their work is that they simply have no experience doing so. Such developers are to be avoided, especially if they are cheaper than others that don’t have this limitation. If anything ever goes wrong with the software, and in my experience it always does, the business is then chained to the developer for help. The developer has it all in their head, not written down, and that is how you make a custom website expensive to maintain.