Documentation Part 3: Getting to the Details

Trying to troubleshoot an IP network without proper documentation is like trying to find your way around a strange city that has few street signs. Here are some tips to ensure valuable airtime is not lost because of inadequate records.

In my two previous articles on documenting IP networks, “How IP is Redefining System Engineering Documentation” and “Documentation Part 2: Designing and Documenting an IP Architecture”, I introduced some of the new records requirements for IP broadcast systems. Let’s get a little more granular.

Below is a list of the different engineering documents a well-designed IP broadcast system should have. These documents are all essential to assure a good design and critical for the proper maintenance of the IP infrastructure. Note that some of the documents are simple text-based files, however other information may require CAD-generated diagrams. Passwords must also be documented and safely stored.

Begin by creating these categories of documentation. You can complete each of the sections and add more as needed, as the system is built.

Breaking it down

Previously I discussed key IP topology components; core switches, top of rack edge switches, satellite switches and firewalls. Such information can be shown in a line drawing. However, what about the network segmentation VLAN’s, access control and trunking. Consider how to best illustrate these network elements.

Some of the required information needs more than a simple line drawing. If SMPTE ST 2110 is going to be individual streams of essence using multicast addresses to and from devices over a network on a single wire, what type of document best captures those intricacies?   

Even a simple high-level block diagram can help engineers quickly identify likely problem sources. Begin with top-level views then drill down with more detailed illustrations.

What about servers that require OS, permissions, application(s) and use API’s or middleware (ie FileZilla) to move files? How will you handle version control and then update the changes? Vendors stop supporting older versions of their software, which means the Service Agreement becomes invalid. Moreover, when vendor A insists on a version upgrade, what impacts will that have on other applications or device connected to it? All of these details need to be carefully recorded. Vendors do not coordinate their upgrade paths with each other.

Here is a list of some essential information needed to maintain a computer-based broadcast infrastructure. Such information is not unique to IP networks; it pertains to most technology and systems. 

Application workflow

Historically, system integration was all about cable and connectors. Today, system integration is about the interface between applications. And what about the communication protocol (json, xml, etc) between them, that needs to be documented as well. Be sure to record which server handles APIs.

CAD-generated flow diagrams can help technicians better understand how signals move within a facility and between devices.

Here are a few more things that need to be documented and managed for IP systems.

Computer-based systems rely on permissions within the environment to communicate with other computers and also humans. Storage locations are mapped and mounted to enable applications to read and write to them. Even devices need user credentials with managed permissions to communicate with other devices. Here are more layers that need to be documented.

Each computer connection will require permissions, and other data. Be sure that information is recorded and updated as needed.

Does this mean no CAD?

Not really, it just has to make room for other tools, spreadsheets, databases and even text docs have an equal, if not greater, role. Here are some examples.

Documentation standards

The broadcast industry actually prides itself on having created an accepted convention of documentation. There are always variations on a theme, but overall there has been consistency in the style of drawings and signal flow. Until now. CAD is not the best application to show how applications communicate. In addition, because workflow is the term everyone uses, how are they best documented?

Documentation accessibility

Finally, once you have developed all this documentation complete with system manuals, user manuals, system configurations, software backups and system records, where should it be kept and protected?

Storing all this critical information on removable media in a desk drawer is not the best choice. Create an engineering and maintenance location in a non-media, controlled access, storage system. Be sure the documentation is kept synchronized as system changes are made. When new gear is installed, assign someone to immediately update the filed information.

At a presentation this past NAB, a marketing analyst proudly claimed a major broadcaster recently finished a brand new $35 million facility that had no IP. If I wanted to pick a fight, my question to him would be, “How many network switches were required, how much storage is available over what number of servers? As a follow-up question, I would ask, was it fully documented?

Editor’s Note: Gary Olson has a book on IP technology, “Planning and Designing the IP Broadcast Facility – A New Puzzle to Solve”, which is available at bookstores and online.

Editor’s Note: Gary Olson has a book on IP technology, “Planning and Designing the IP Broadcast Facility – A New Puzzle to Solve”, which is available at bookstores and online.

Let us know what you think…

Log-in or Register for free to post comments…

You might also like...

Essential Guide:  Audio Over IP - Making It Work

Audio over IP (AoIP) has become one of the most important technologies to ever enter the media landscape. The protocol allows facilities to leverage today’s mature IP platforms for audio applications resulting in lower costs, faster installations, improved quality o…

Articles You May Have Missed – June 20, 2018

Until now, 4K/UHD and high dynamic range (HDR), in many ways, has been little more than a science project, as manufacturers have struggled to convince production entities of the long-term practicality and viability. Fears of overly complex pipelines and…

Are Helium-Filled Hard Drives More Reliable Than Air-Filled Drives?

The first commercially available helium-filled hard drives were introduced by HGST, a Western Digital subsidiary, in November, 2013. At the time, the six terabyte device was the highest capacity hard drive available. Backblaze, a major hard drive user, wanted to find…

Broadcast For IT - Part 11 - Sensors

In this series of articles, we will explain broadcasting for IT engineers. Television is an illusion, there are no moving pictures and todays broadcast formats are heavily dependent on decisions engineers made in the 1930’s and 1940’s, and in this art…

A Brief History of IP - Putting It All Together

Building reliable, flexible IP networks requires an understanding of infrastructure components and the interoperability of systems that run on them, especially when working in fast-paced, dynamic studios. Protocol interfacing is relatively straightforward, but as we investigate application level connectivity further,…