Management and oversight of a web development project for small businesses, part 1: a tour

Many small businesses, whether run by tech-savvy individuals or not, are unfamiliar with (1) the infrastructure that makes the web work; or (2) what to expect from a web developer; or (3) the nature of software projects; or some combination of the three. This prevents small businesses from seeing where and how to maximize the value they’d get from hiring or bringing a web developer onto their team.

In this post I have assumed: (1) that you are deeply involved in some kind of small business; and (2) that you either do not have a website, or you have a website but it is in need of updating to fit business requirements.

Below I provide a overview of some of the key areas of the web development field that small businesses should acquaint themselves with. If you are deeply involved in a small business and you are in the process of bringing on a web developer then know that you should delve deeper into each of these topics, much further than I am going here. Consider this a tour of the material you should work to understand.

And… one more thing before we dive in. I want to be clear: I am not suggesting that you learn to code. I am suggesting that you understand the technical-side of the business. However, If learning to code is your thing and you want to do it, then, by all means.

Web infrastructure

As the person responsible for managing a website it is important to have at least a rudimentary grasp of how the web works. There’s quite a bit of infrastructure underlying a website. The business you purchase a website domain name from is called a registrar. The particular business you used may not refer to themselves as a registrar, however, they are a web host or platform that also happens to offer registrar services. Whether you used a proper registrar or not, which ever company you purchase a domain name from is the registrar for that domain. Your registrar is responsible for handling some crucial data that allows your website to be accessible to users on the internet.

The information you provide to your registrar, such as your contact information and name server entries, are recorded in the WHOIS database. The name server entries you provide to your registrar are used by DNS so regular users browsing the internet can connect to your website.

All this information is public, contact information included. While ICANN, the company that coordinates management of WHOIS services, stores only your current contact information in the WHOIS database but effectively all current and prior contact information is public. This is due to the nature of the web. Anyone can find the prior contact information of a domain from one of many resources that scrape data from the public WHOIS database. Do not provide your personal contact information in place of the appropriate contact information for the business. It is possible but not feasible to remove this information from the internet once it’s been made public.

Your registrar makes your list of name servers available to the WHOIS database and DNS servers. DNS clients use the DNS protocol to find your name servers. Your name servers report to DNS clients which web server the user should connect to in order to access your website. Mobile applications that need internet access, desktop applications that need internet access, iOS, Android, Windows, macOS, Linux, etc., all have built-in DNS clients. This includes your web browser. The list of name servers that you provide to your registrar are often supplied by your DNS host, if you have one, otherwise, your web host.

The architecture of the web is distributed, and the implications of being distributed may not be clear. First, since your registrar requires a list of name servers from your web host (or DNS host), you can choose your web and DNS hosts firsts, and even get a website up-and-running without having chosen a domain name yet. Each web host provides either an IP address or subdomain for you to access the website. Once you choose a domain name you’d login to your registrar and update the list of name servers to point to the appropriate ones from your web or DNS host. While this process is the reverse of how most people and businesses operate, it’s technically possible and well-supported, and if a business hasn’t decided on a domain name yet—that’s ok, there is no reason to have that hold up a project. More practically, this distributed nature means you can use business A as a registrar, then you could use business B as a DNS host, and then you may even use business C as a web host. It is not necessary for each service to be managed by a single provider.

Additional Resources

1. https://lookup.icann.org/en - ICANN WHOIS lookup tool
2. https://whois.icann.org/en/basics-whois - ICANN WHOIS educational material
3. https://whois.icann.org/en/dns-and-whois-how-it-works - ICANN DNS & WHOIS - How it Works
4. https://mxtoolbox.com/ - DNS lookup tool
5. https://howdns.works/ - DNSimple’s “How DNS Works” comic
6. https://www.icann.org/en/blogs/details/do-you-have-a-domain-name-heres-what-you-need-to-know-part-1-31-8-2017-en - ICANN on managing a domain name; part II, III, IV, V, VI, index—some parts more useful than others

Expactations of developers

Most small businesses expect a web developer to deliver an update to an existing website or to conjure up a fully functioning website. Hopefully the developer also sent you tarball or zip file of the source code or pushed the code to a repository under your control. If you’re not familiar with source code repositories, such as git or github, then ignore that for now but plan on learning about it later. It is important for you to have a copy of the complete website source code. The source code must be stored in an accessible location, and ideally a backup copy somewhere, e.g., a USB flash drive. It’s not sufficient for the only complete working copy of the source code to be the one running on the web server.

Every time your website is worked on, you should be requesting a new, updated tarball or zip file after they work on it. If you have a long-running project then you should be requesting updated tarballs and zip files every week or two. If you’re using a source code repository then you should also be aware that you can glance at the commit history and see when the last time the website has been worked on.

There will be times when your business needs to modify the website but the developer familiar with the project is unavailable. If you do not have the source code stored in a readily available location then you are going to have to pay for a new developer to recover the source code from a live web server, assuming it’s even accessible, or otherwise this new developer will have to scrape what code they can from the existing client-side portions of the website and then recreate the backend code themselves. If you end up in this situation, you will be paying a developer to recreate what already exists, but effectively no one has access to. This is a significant waste of resources—both time and money. This is why you need to make sure the source code is up-to-date and accessible.

Another expectation mismatch between developers and small business owners stems from general unfamilarity with software and its capabilities. A functioning website isn’t the only output the small business should be receiving from the developer. You should also be expecting: (1) tests to ensure the website and source code operates as expected; (2) a list of project dependencies including the platform and web server software that the project currently runs on; (3) documentation on how to the initial setup of the web server and website; (4) documentation on how to deploy updates to the website; and more depending on the type of project. I consider the above to be a minimum for any web development project.

All these can be stored in the source code itself. Some people prefer to manage these these in documents on shared drives, or wikis, or other places. The location is unimportant. What matters is that there is some place this information is recorded and that it can be handed to any developer that works on the project. I prefer code over documentation, and in general, you should too. For example, if there is a deployment script (a short computer program) for pushing updates to the website, stored with the rest of the website source code, then the documentation may simply state “Deploying Updates: See bin/deploy”. That is perfectly acceptable.

Nature of software projects

There seems to be a widely held belief that once software is written it will work, and work correctly, forever. Unfortunately, that is not reality. Due to both business and technical demands, all software must be maintained.

Software is tightly coupled to business operations and requirements and must be modified to accommodate requirements as they change. Often requirements do not change delibrately, but rather, they drift from what was once the common procedure. For example, at many small businesses a single individual fills multiple roles. Consider an individual doing admin work on user accounts and also doing sales. When doing sales calls this individual could simply look users up through the admin portal that they already access. Once the business is large enough to have a dedicated sales operation it would be inappropriate for the sales team to be using the admin portal. The sales team would be given way more detailed information about user accounts than they need and would be appropriate. Additionally, the admin portal is built for administration, and you wouldn’t want to build out the portal so its usable for both sales and admin simultaneously—the UI would quickly become an incoherent mess. Changing requirements, both deliberate and by drift, is just part of the story of why software must be maintained.

Similar to the business-side of things, the technical-side of a website also changes. A modern web server runs a lot of additional software on the periphery. While this software is very stable, it’s not uncommon for a web server, database, SSL/TLS certificate, or SSH software or configuration to have to be updated. It’s rare for an update of this nature to be problematic, however, but it still requires maintenance. For security reasons, it is unwise to go more than a week or two without updating the software of a public facing server on the internet.

Up until now we haven’t even touched on the particulars of your website, and the specific reasons why it must be maintained. All prior examples are reasons and examples of how business requirements demand maintenance, and how the software necessary to run a website necessitates software maintaince. However, your website itself, even if custom built, will depend on a framework, libraries, and other dependencies—this is the software that is intertwined with the code that runs your website. All this requires some maintenance.

From how I’ve outlined things here, it may seem as if all software work is maintainence. As a developer, it does feel like that on occassion, but upgrading libraries, modifying configs, etc., is largely fast and painless. Making changes to the software to accommodate these updates is negligible. In rare cases, maintenance may mean changing web servers, or relational database management systems, or migrating from one framework to another. Modifying the software to accommodate these kinds of changes are painful and time-consuming.

End of the tour

That’s it for now though. Hopefully you got something out of this post. In the coming weeks I’ll try to elaborate or extend on various pieces of this article.