2021.12.26: Document Decisions

Context

I created andrewsforge.com in June 2010, with the first deployment occurring in July 2010.

At the time, colleagues recommended that I buy a shared hosting plan and that I upload files to the shared server via SFTP to deploy the site. A few recommended I find a hosting plan that included CPanel. Others recommended GoDaddy, which included CPanel. This all seemed sensible: I had deployed my first website in 1998 using a similar system. I made a decision quickly, and the final solution felt comfortable.

Years later, out of frustration with GoDaddy, I migrated the site to A Small Orange and NameCheap.com. Even then, the system remained the same: I would create HTML and CSS by hand, and then SFTP them to the shared sever.

The landscape for creating and deploying personal websites since I deployed my own has transformed. The list below illustrates the landscape in July 2010 and how it has evolved.

  • HTML 5 was announced in 2008, but would not reach full specification until 2014. CSS 2.1 was a working draft, and would be released in 2011.

  • The ECMAScript 5 standard was released less than a year before, and the web used JavaScript following the ECMAScript 3 standard. Node.js was demonstrated at JSConf less than a year before and NPM was 6 months old.

  • JQuery was the popular JavaScript library to use. AngularJS would release later in 2010 and ReactJS would release in 2013. VueJS would follow in 2014.

  • PHP 5.2 and PHP 5.3 were the current releases of PHP. In 2021, the latest release of PHP is version 8.

  • Python 2.7 was released only a few days before I published my site. Python 3.2 would release the next year. Django 1.2 was a month old.

  • The Go programming language had been announced in November 2009, but would not reach v1 until 2012.

  • Companies I consulted for in the summer of 2010 were still debating the utility of Version Control Systems (VCS). Those that were using VCS used SVN and debated a migration to Mercurial, Bazaar, or Git.

  • Bitbucket and Github launched in 2008, but the latter had not yet become the content center it is today. The Gitlab project would start in 2011.

  • The Jekyll static site generator—frequently credited as being the first modern static site generator despite the existence of tools like blosxom & Yggdrasil—was less than two years old. The Middleman static site generator was a year old. Pelican's first commit would occur several months after I published my site. The Hugo static site generator would release in 2013. GatsbyJS would release in 2017.

  • Amazon Web Services launched in 2006 with only Simple Queue Service, Simple Storage Service, and EC2 Compute. Between 2006 and 2010, only 9 other services were added:

    • SimpleDB
    • Elastic Block Store
    • Cloudfront
    • EMR
    • Cloudwatch
    • Elastic Load Balancing
    • VPC
    • RDS
    • Simple Notification Service

    Identity and Access Management would be added in late 2010. In 2021, AWS comprises over 200 services and products.

  • Google and Microsoft both launched their own clouds in 2008 but were still not considered competitive with Amazon.

  • Cloudflare was a year old, and Fastly would launch in 2011.

  • Netlify would launch publicly in 2015.

  • The first commit to jamstack.org would occur in August 2019.

  • The General Data Protection Regulation (GDPR) privacy laws in the EU would be adopted in 2016 and enforced starting in 2018.

Problem

During the entirety of Python 2.7's release, lifetime extension, and deprecation, my front page's CSS file has been named temp.css (short for temporary). It is well past time I update my website.

In the last 11 years, the web has matured and become more complex. There are more options for how to build web sites and web applications, and tools for testing and deploying websites have improved by leaps and bounds.

However, this increased complexity means that I must make more decisions about which tools to use.

Due to my career and personal life, I have less time today to devote to a personal website than I did in 2010.

The combination of increased complexity and decreased availability has led to a frustrating stalemate.

I have attempted to use different tools to create a new website, but my efforts ultimately stall. Typically, I will have a weekend to focus on the site, and then I won't be able to return to the project for a month (or more). By the time I return, I can no longer remember what I was doing. Previous research, choices made based on that research data, and the state of the code are all unknown to me by the time I return to the project. It becomes impossible to pick a path forward, and so the cycle of research and prototyping begins anew. This has been an excellent way to learn new tools and technologies, but an inefficient approach to designing, building, and deploying a new website.

I need a mechanism to combat the situation.

Decision Drivers

The solution must account for:

  • returning to work after time away (i.e.: my busy schedule)
  • increased cognitive complexity

Considered Options

  • abandon personal website
  • use commercially available off-the-shelf (COTS)
  • outsource decision-making process
  • divide, conquer, and document work

Pros and Cons of the Options

Abandon Personal Website

While this directly solves my scheduling and cognitive load problem, it also prevents me from having a place to write and share my work, which is undesirable.

Use Commercially Available Off-the-Shelf (COTS)

I could use a service like Ghost or Medium to reduce the cognitive load. But, the reduction in complexity also reduces the flexibility of what I may build. Reducing my choices also reduces my options. I do not want to limit my technical choices or my branding or marketing options.

Outsource Decision Making Process

I could ask others to do work for me, addressing my overburdened schedule. But, finding talented engineers is hard. I spend a lot of my time at work on the hiring process, and hiring has only gotten harder over 2021.

In 2019 I have attempted to hire freelancers to help build parts of my site, and the process was disastrous. While this solution option attempts to address my schedule, I suspect it would actually aggravate the problem.

Divide, Conquer, and Document

This option attempts to address cognitive complexity. Instead of reducing complexity, the solution focuses on the problem of returning to a complex problem. I would focus on a single problem at a time, and write documentation as I work. This documentation would include a defintion of the problem, research related to the problem, and the final solution. In the event of new tools or technologies, I would be able to review past research and decisions and leverage the knowledge into a new decision.

Documenting each task expands the scope of every task. This will slow down the rate of work. But, it ensures that the problem is clear, and that research and final decisions are not lost. In theory, this will increase the velocity of the project.

Decision Outcome

I will begin to document my research and decisions as I work.

I will create a new site to store these documents.

Positive Consequences

I retain all of the flexibility of building a custom, personal website with any desired technology and personal branding.

Negative Consequences

The cognitive complexity of the terraformed technical landscape is not directly addressed. My limited schedule is not directly addressed.

Documenting all of my decisions will require more work. Notably, the act of documenting technical decisions is difficult.

Creating another website to display these documents is additional work.