Digital definitions

The purpose of this page is to present definitions for technical jargon and explanations around related technologies. The intended audiences are people who might not be familiar with development tools and methods nor our unique requirements when working on items like about.gitlab.com.

Pages

What is a page?

A page is a final or near-final product, a unique instance of something generated from a template. This page has an expected URL where it will be accessible in a live environment.

Templates

What is a template?

A template is a data-driven reuseable configuration used by certain types of content. A template consists of choosing a set of blocks, a configuration for the blocks, and a configuration for the page options.

Example: all blog posts are generated by the same template.

Related terms: layout.

Why are templates important?

1. Templates facilitate quickly duplicating setups.
2. Templates reduce configuration errors by codifying configurations.

Blocks

Related terms: partials, includes, fragments, organisms, molecules.

What is a block?

1. A section of the page, generally kept as small as possible. It’s usually a horizontal slice of layer cake across the page but can also be a chunk of a sidebar.
2. A block is a section where the presentation, goal, and required functionality remains the same, but content can be updated (wording, imagery, links, etc).
3. Blocks are often made up of many elements and components put together and organized around a common purpose.
4. Blocks might have configurable options to facilitate reuse with different configurations. It is always be desirable to have a title block for example, so there might be an option to turn that off.

Example: A gated content form.

Why is it important for a block to be reusable?

1. In order to facilitate updates, the code needs to be reusable. It’s not an easy update if you have to build it again.
2. Implementing the same thing over and over again is not an efficient use of resources.
3. In order to keep the codebase clean, navigable, and easy to understand it’s important to maintain SSOT.
4. If the same code is implemented several times in several spots then the chance for bugs increases. One of those spots might have a bug where the others don’t.
5. Much of what goes into building code is unseen on the page. This includes things like optimizing performance, setting up tracking, preparing assets such as formatting images & videos, building responsive views and layouts, human physiology (fingers on a touchscreen, eyes and perception, etc). Testing and building all of these things takes time, so it’s important to reuse and reduce code as much as possible.

Why is it important for a block to have a single-purpose?

1. In order to facilitate updates, the code needs to be easy to operate.
2. Having a clearly defined purpose for each block enhances the goals of the page and assists with navigation and conversion goals. If a block tries to do 5 things or there are 3 different blocks on the page doing the same thing it becomes difficult to manage.
3. An end user might be confused if duplicate blocks are on the page.
4. If a block gets too large then it becomes harder to understand the code. Keeping a block single-purpose keeps the block small.
5. Tracking the performance of a block becomes more difficult the more a block changes.
6. When examining from a distance, it’s hard to know what block to use if the blocks all have several different purposes, sometimes overlapping purposes. “Do I use this block or that one?”

Components

Related terms: molecules, modules

What is a component?

A component is conceptually similar to a block, except it’s often quite a bit smaller. A component combines elements into a small item with a singular purpose.

Example: A search box is made up of a text input element and a submit button element.

How is a component different from a block?

Components and modules differ mostly in size and purpose. The singular purpose of a module might be to get someone to sign up for a newsletter. This might include a description, a title, some graphics, margins, padding, and other elements. The singular purpose of an component would be to gather the email in a text input and submit that with a button. A component often lacks the context that a module has.

Why are components important?

1. As mentioned above, blocks and components are conceptually similar. Components benefit from the same things that blocks do.

Elements

Related terms: atoms

What is an element?

An element is the smallest reuseable thing.

Examples: a button.

Why are elements important?

1. Reusable elements serve to solidify a brand by building a cohesive identity.
2. Elements facilitate efficiency by creating a kit of parts so we don’t have to create the same thing over and over again.
3. Elements facilitate predictable outcomes by creating constraints around possibilities.

Content management systems

What is a CMS?

A CMS (content management system) is used to manage the creation and modification of digital content. Usually a CMS has

• An editor interface (WYSIWYG) so content producers don’t need to know how to build a website in order to create content.
• A persistence layer that stores data from the editor interface.
• A view generator that combines raw content with templates in order to generate pages.
• (optional) a server that responds directly to user requests and customizes pages based on requests.

What a CMS isn’t

• A CMS doesn’t define requirements.
• A CMS doesn’t create layouts.
• A CMS doesn’t create modules.
• A CMS doesn’t define templates.
• A CMS doesn’t ensure best practices (though it can encourage them).

Headless CMS

What is a headless CMS?

A headless CMS is a CMS that abstracts the business logic away from the display logic, usually via two or more separate interfaces. A content editor doesn’t need to interact with the programming and a programmer doesn’t need to interact with the content. In a non-headless CMS the two interfaces are intertwined.

Statically-generated

Also referred to as SSG (static site generation/generator)

What is a statically-generated website?

A static web page is delivered to the user’s web browser exactly as stored, in contrast to dynamic web pages which are generated on-the-fly by a web application after an end-user request for something such as data modification.

SSG benefits

• Significantly faster for the end-user in many situations.
• Easier to work with for developers.
• Fewer dependencies on cloud systems.
• Improved security.
• Costs less to host.

SSG complications

• Dynamic functionality must be performed on the client side.

Continuous Integration

What is continuous integration?

Continuous integration means any time a change is merged into a revision controlled branch, it is automatically released live. This is in contrast to a manual release process. This automatic release is dependent upon several additional processes and numerous other parts of the puzzle such as operating system, networking, and server technologies.

Pipelines

A pipeline is a group of tasks that need to be completed in a certain order. Before X can happen, Y also needs to happen. That would be an example of a singular pipeline. Another pipeline can be processed in parallel, assuming that it doesn’t need X or Y to happen first. If pipeline A needs Z to happen first, it can be done in the same pipeline as Z or in as a second pipeline that starts after Z.

Automated tests

In order for a build to succeed, we need to ensure the components aren’t broken. This means that automated tests have to pass before a build can start. That said, there are also unforeseen circumstances which can cause a build can fail regardless of testing.

Note that automated tests can happen at any time before, during, or after a build or deployment.

Build phase

Once an item is merged and automation passes, the related code needs to build an application to release to the server. This might be a SSG, it might be a CMS, it might be updates to the server or operating system, or some combination of those things, it could be anything really.

Build times depend on the number of items being changed, how they’re being changed, how many things are cached, how many third parties are being polled for resources, how quickly the third parties respond, and how many cloud resources are available.

Deploy phase

A build must be deployed to a location, either for testing or for live release.

Deployment times depend on the amount of data being deployed, the data transfer speeds, and the number of deployment destinations.

After deployment

Just because a build is deployed doesn’t mean it’s live. Other processes might need to happen. Examples of this include:

• Search engine indexing.
• Scheduled tasks such as cron to process or update data.
• Updating caches such as images.
• Propagation across a CDN.

CI complications

• The ability to update things quickly is dependent on build time and pipeline reliability.

Client-side vs server-side

Client-side

An end-user’s web-browser is responsible for client-side tasks. Once a server delivers a document to the end-user, it’s up to their computer to modify the document on their computer. Alternately they can make a request for the server to modify the document for them server-side.

Server-side

Anything not done on an end-user’s computer often needs to be processed by an invisible web-server. Once processed the server sends a new version of the page to the end-user or routes them to a new location.

CDN

What is a CDN?

A CDN, or content delivery network, is a way to facilitate speedy delivery of applications and resources to someone who might be far away from a server. A CDN caches a local copy of the webpages closer to the physical location of the end-user requesting those pages.

CDN complications

• It takes time after deployment to copy, or propagate, all changes from a live server across to all destinations in a CDN.
• Any endpoint on a CDN might become corrupted, serve incorrect resources, or serve an expired cache. Without appropriate logging and end-user bug reports, these kinds of problem can be incredibly difficult to track down.

Monorepo

What is a monorepo?

A monorepo (short for mono-repository) uses a single location to store the code of many different projects. It’s similar to living in a condominium complex where you can share benefits and responsibilities among several families versus living in separate houses in the countryside and being responsible for everything on your own (20 lawn mowers vs 1 lawn mower, etc).

Why monorepo?

• To facilitate SSOT single source of truth.
• To facilitate sharing of resources and build systems.
• To simplify dependency management.
• Making changes in one location can benefit multiple systems.