Dependencies between WordPress core, plugins, custom code, or other components will always add complexity to the WordPress ownership experience. Complexity adds cost.

Good documentation is the enemy of complexity. It inoculates against the rampant spread of unanticipated costs by providing a road map which the appropriate audience can then use to keep the site viable and relevant. Those that maintain the website, or are hired to continue its evolution, can do their jobs much more efficiently if they know exactly what they are dealing with.

But where to start? After all, WordPress builds can involve significant complexity. Why not just rely on developer notes? Websites that have any sort of workflow to them, such as e-commerce or membership sites, usually have a list of use cases and associated requirements that determine the final build. While most developer’s notes are invaluable for understanding details that should not be forgotten, they are usually not written around the concept of an overall “Site Integration Map”; a document that describes dependencies, security considerations, and other aspects of the build that are important for technologists to understand.

One way to think of it is like this: While user manuals tend toward a workflow-centric view of the website for end-users, integration maps are meant for technologists that need an architectural view of the website based on the use cases the workflow evolved from.

What It Is

An integration map for a WordPress site is an architectural, technical document organized primarily around use cases. It may contain excerpts from developer notes, or it may double as both a site integration document and developer notes. Like most technical documentation, its actual nature is influenced by the context of the situation. It is the map by which navigating a website’s complexity becomes less problematic.

Consider this example from a WooCommerce site built to house thousands of inventory parts in a strictly private, inside-sales environment. Here we start the document with an Overview, which is in fact taken from parts of other documents. It doesn’t matter where you get the content for the Overview, just so long as it provides the required context for a technologist to understand what they are about to get into:

OVERVIEW — -

This website is constructed on WordPress using the iThemes Builder “Thrifty” theme and a variety of plug-ins, all tested for compatibility with each other and common security practices.

The website supports two different user role experiences, one for Customers and one for Distributors. Customers are businesses that own and use the company’s machines. Distributors are businesses that sell to Customers.

When Customers login, they get an option to go to Machine Management (MM). The MM page is a customized construct that shows machines at the top (only 2 were originally requested, but after implementation this was expanded to 10, see Change Request 1022) and parts related to their machines (automatically filtered through code) on the main body of the page; which itself is furnished through a WooCommerce shopping configuration.

Distributors are taken to a landing page containing the option to visit their Hub Page. This is furnished through WP-Client. The system requires that company staff add Distributors manually (Requirement 32.5), and then invite them to their hub page. As requested, there is no secure mechanism in place for Distributor or Customer self-sign-up. Instead, a simple workflow allows company staff to bring the client to the website and perform the remaining actions that will grant them the required access themselves.

— –

Use Cases then become the titles for each subsequent section of the document, organized in whatever manner makes the most sense for this particular build. Here’s a section related to user self-registration. Imagine if the client (or more commonly the client’s employee) tried to turn on user self-registration themselves, then called the help desk to find out why it wasn’t working. Then again, perhaps another developer is hired, the client’s personnel changes, and someone decides it’s time to allow user self-registration. Either way, to deal with this request the technologist involved is better off having access to the following information as a section in the site integration map:

USE CASE: SELF-REGISTRATION PROHIBITED — -

The site is configured at a very deep level NOT to allow user self-registration. This includes security approaches to prevent such a thing.

In functions.php this code removes UI elements that could allow someone to attempt self-registration:

/** * remove the register link from the wp-login.php script */

add_filter('option_users_can_register', function($value)
{ $script = basename(parse_url($_SERVER['SCRIPT_NAME'], PHP_URL_PATH));
if ($script == 'wp-login.php') { $value = false; } return $value; });

WP-Client and WordPress are also set NOT to allow clients to self-register.

Context Is Everything

Terminology is important when defining abstract concepts, and such definitions are critical for reducing complexity. Here we clarify what certain words mean and how they manifest in WordPress before we discuss the use case in question:

— –

Machines, Products and Customers
This system can be used to create a relationship between WooCommerce products and a WordPress user account in the role of Customer. Any product can be a machine, and any machine can be assigned to any customer. Machines can have a PDF file associated with them for easy access by the Customer as displayed on their Machine Management page.

USE CASE: MACHINE ASSIGNMENT TO CUSTOMER
A Machine is a WooCommerce Product that has been assigned the category of Machine. Once that is done, the Machine can be assigned to the Customer by visiting their Profile. On that page, scroll to the bottom and you’ll see the machine as an available checkbox item.

The functions.php file and the plugin MachineXT we created are relevant to this ability.

— –

Some of this text might even appear in the user guide or these concepts demonstrated in training videos.

Why It Matters

An integration map’s value becomes apparent in the elimination of one question, “How did we (or they) build that, again?” Most of the time that question is asked when something goes wrong or the site needs to be enhanced. It is usually asked in relation to a feature that holds up part of a workflow. This is where an integration map organized around use cases helps.

Clients will appreciate these documents, even if they cannot understand them. It communicates transparency, but it also alleviates fears that if something happens to you or your agency they would have nowhere to turn. Reducing fear reduces the objection to the sale. Site integration maps can, therefore, be marketable aspects of working with you. They demonstrate you know what you are doing, and that you keep the client’s best interests in mind.