What is a PDK or Programming Scope Document?

Ian Bryant | Oct 23, 2019

I recently led a discussion panel about large integration projects, how to manage them, and the pitfalls that accompany them. The panel featured representatives from integration companies that are creating some of the largest home integration systems in the world. We covered a lot of topics, but the conversation almost always came back to two key items:
  • Documentation
  • Client communication

How can a company document and convey the operation and function of a large and complex integration system in someone’s home? That is where the PDK (Programming Design Kit) or Programming Scope Document come into play.

When an integrator is conducting client interviews or is in the discovery phase with a client, they ask lots of questions about that customer’s home life, how they use their current technology, how technology could help simplify their daily routines, what areas of their home they use the most, and many other questions. This gives the sales and design team a starting point to suggest what technology could be implemented to help make the client happy about being in their home. Once the technology has been selected and designed, the next step that sometimes gets left out is the fine detail of how the integration system will look, feel, and operate. This system may not be fully customizable and configurable, it may not even be one of our own — it could be the client’s smart phone or tablet. But this must be discussed before the client signs the dotted line agreeing to a design that they will live with for long time.

This is why integrators should create and present a PDK or Programming Scope Document to their client. Whether the project is a million-dollar theater or a small integrated home, every client should receive this type of document. The document will vary in size depending on the complexity of the system that it is being written for, but it should be utilized in every integration.

As an example, one might think that a small integrated home utilizing a smart phone application for each of the subsystems would not need such document, but that is not correct. Your client does not know how these applications work, look, or feel. Making sure that they understand the capabilities, limitations, and usability of these applications is necessary. Your client may see these and decide that they want to upgrade to a unified control system, or they may decide that some of these products are just not giving them the level of control or ease of use they need. This is where the documentation and communication you have with them is key.

On the other end of the spectrum, the larger and more complex home integration systems with unified control systems and customizable user interfaces must also have these documents. Your company may have UI (user interface) layouts that you use for all of your jobs and that have stood the test of time for your clients and system designs that are easy to operate and cover all bases. However, even if this is the case, it is still important to run through this with your client and document it for them. With the price tag that comes with these larger, more complex systems also comes a client that feels very passionately about this system and how it looks and operates

There are many sample documents out there that can be customized for your application. Some manufacturers have downloadable kits to use or you can create your own. Whatever direction you decide to go, just remember to document everything and keep an open line of communication with your client.

So, what should be in a PDK document? Some of the more important items are:

  • Descriptions of each subsystem being integrated and how these systems will be operated  through the control system
  • Descriptions of each type of user interface in the client’s home
  • How to operate each of the different types of user interfaces in the system
  • The shapes and colors that will be used for the interfaces
  • Images or logos used on the user interfaces
  • Smart phone applications and how to operate them
  • Automated event descriptions and how they function
Why is a PDK document so important?

  • Your client will know what to expect when you turn the system over to them
  • They will know exactly how to use the system and will feel that it is “their system” that they helped to create and customize
  • You will have a signed agreement with your client of how the system operates and what systems are going to be controlled
  • It will help you discover any bottlenecks in the systems or possible failure points prior to implementation
  • It can serve as a protection document against scope creep if your client requests additional system operations that weren’t discussed
  • It will serve as a user manual for your company, the client, and any possible future tenants of the space it is installed in