Latest Work

I HAVEN'T BEEN blogging much until lately, because I was busy writing technical manuals for TechGuard Security, an Internet security firm based in Chesterfield, Missouri. Here is the beginning of one of the manuals I wrote for the PoliWall-ESE Security Appliance:

Copyright © 2010 by TechGuard Security L.L.C.  ALL RIGHTS RESERVED. This is used with permission from TechGuard Security. Please note that the image of the PoliWall used here is a placeholder and will be updated with a photo of the actual unit (although it looks pretty much the same). Undoubtably this documentation will change in the future as the product is further enhanced, and what I show here are merely examples of my writing.

Among my best teachers back at Affton High School was Miss Doris Ahrens, R.I.P., who taught English Composition. Even though she had the reputation for being a tough grader, and required a lot of homework, my brother had a high opinion of her methods and strongly recommend that I take her. She required her students to write every day — not only did the writing have to be technically good in itself, it also had to be presentable. This proved to be of great value in the future.  Computer programmers often have the reputation of not liking to document their work: after all, if a program was hard to write, then it ought to be hard to use. But I've always had a fondness for good solid documentation.  Thanks in part to the good discipline instilled by Miss Ahrens, as well as a later love for grammar, words, and literary style, I rarely had a problem with writing it.

You never know who is going to read your documentation. So before I started writing, I made a plan: I'd try to write the document so that readers of many levels would be able to get at least something out of it. The first paragraph is for the bosses, administrative assistants, and purchasing agents who may pick up the manual wondering what is this thing we bought?

The PoliWall-ESE^TM is a device which blocks unwanted Internet traffic from entering your computer network, and it prevents your own computers from sending information to suspicious locations. This device's great innovation is that it quickly determines the country of origin of Internet traffic. You can easily deny communications with countries of your choosing, by a simple click on the PoliWall's world map. The PoliWall automatically blocks known Internet threats, based on lists provided by TechGuard Security. You can allow Internet sites you know are friendly and block those you know are hostile. The PoliWall-ESE constantly monitors your network, alerting you of suspicious activity, while automatically taking evasive action. The PoliWall saves extensive audit logs for your review, and presents online charts showing your network's current status. This device is fast, secure and easy to operate.

I hope this is understandable and reasonable, as well as reassuring to decision makers who may never be quite sure that their subordinates' purchase requests are for something truly needed.

I naturally write in the passive voice, which is a mode of speech that is sometimes appropriately non-specific, but which can be downright weaselly. Perhaps this tendency is a part of our fallen human nature. But I attempted to keep most sentences in the active voice, which is both more vigorous and also more precise, if less poetical. The manual is mainly in the active voice, which can make it somewhat wordy. However, in the active voice, you the reader are the actor.

A photograph between the first and second paragraphs serves as a visual signal of a change in emphasis, a method I tried to use throughout the manual. The next paragraph is far more technical:

The PoliWall-ESE^TM resides between your firewall and Internet connection, where it acts as an OSI Level 2 network bridge, and so is invisible to the Internet. The PoliWall incorporates the unique HIPPIE^TM (High-speed Internet Protocol Packet Inspection Engine) technology, which determines the country of origin of each packet, and filters inbound and outbound packets at wire speeds. You can create many filters for the PoliWall, based on country and IP network, and you can add exceptions to these filters. The PoliWall can automatically download updated lists of known threats such as spammers and botnets. You can define the Quality of Service for countries and networks of your choosing; you can also throttle traffic according to custom filters. You can define alerts, and automatically throttle suspicious traffic. You configure the PoliWall from a standard web browser, and this administration function is protected by multiple levels of security including Public Key Certificates, trusted network lists, and administrator passwords. The device supports both IPv4 and IPv6, and can be managed via SNMP.

This ought to satisfy experts in computer networking, telling them concisely what they need to know. The next paragraph serves as a warning, but not without some hope:

Network administrators familiar with the Internet Protocol Suite ought to configure the PoliWall. This manual provides a comprehensive description of the features and utilities of the PoliWall.

Because we live in a fallen world, there will be bosses who are ignorant of the capabilities of their subordinates; workers who cultivate the appearance of expertise rather than its reality; and there are those poor workers who are promoted to a level beyond their abilities. So I attempted to explain concepts basically. Ideally, “Network administrators familiar with the Internet Protocol Suite” would not need any explanations of concepts, rather, they would merely need to know how these things are implemented in this particular device. Undoubtably, there will be administrators who will have little knowledge of the concepts used here, and for the sake of these administrators, their organizations, and for TechGuard's technical support group, I attempted to both add explanation as well as promptings for further reading.


Encryption of Internet data can be particularly difficult. Here I attempted to provide a mixture of basic and advanced information.

Your PoliWall comes with strong data encryption, securing the communications between your PoliWall and web browser. This feature prevents wiretappers and eavesdroppers from deciphering your PoliWall communications, and may be particularly useful when you access the PoliWall from a public network. This security is part of the default PoliWall configuration, and you don't need to do anything to take advantage of it. You can be confident in this security when you see "https://" in the address bar while accessing the PoliWall:

[image omitted]

You can also identify secure communications by the padlock icon at the bottom of the browser window:

[image omitted]

The https web browser function uses a secure Internet protocol along with an encryption certificate installed on the PoliWall. Transport Layer Security (TLS) and Secure Socket Layer (SSL) are Internet-standard protocols that encrypt communications within applications such as web browsers or electronic mail. TLS and SSL get their encryption parameters from an SSL Certificate which comes pre-installed on the PoliWall. Since TLS and SSL are application-level protocols, here they only encrypt your web browser communications. If you want to encrypt all of your communications to the PoliWall, you can configure Internet Protocol Security (IPsec).

SSL Certificates are a type of Public Key Certificate, or electronic document based on the X.509 standard. X.509 is a framework for establishing a public key infrastructure, which specifies formats for Public Key Certificates, and which specifies methods for authenticating these certificates via trusted Certificate Authorities. A certificate contains a public key used by other computers to encrypt data; the certificate holder also has a private key, which alone can decrypt the data, guaranteeing data privacy between the machines. Optionally, a certificate may be authoritatively signed: a trusted firm or organization can apply a digital signature to a certificate, giving you confidence that the computer with that certificate is what it claims to be.

A new PoliWall has a single self-signed certificate used to encrypt communications between the PoliWall and your web browser, but this does not provide authentication. You can install an authoritatively-signed certificate in your PoliWall, and you can optionally install public key certificates in your web browsers, authenticating the administrative computers.

By default, the PoliWall will communicate with any computer, since the PoliWall does not require them to have public key certificates. In this case, security is based on administrator account passwords and optional network restrictions. This basic security may be adequate for many users, and be aware that enhancing this security requires considerable effort, coordination, follow-up activity, and possibly expense.

Things written in bold lettering are key concepts, and typically are also found in the glossary, where I provide simple definitions. Upon re-reading this, there is certainly room for improvement, most specifically with fourth paragraph, which really ought to be broken up and rearranged.

By the way, I also wrote a Quick Start Guide, which will give experienced professionals the basics needed to get their device up and running quickly. But there are those workers who think they already know it all (such as myself), and will plow forward, missing slight, but critical details. So I loaded the Guide with repeated advice:  Read the Manual.  Also, I purposefully created the simplest example scenario that would work most of the time.

Our culture is very good at examining material and efficient causes, in the Aristotelian sense, but is often terrible at understanding formal and final causes, even to the point of denying the latter. This is ironically due to a narrow understanding of Aristotle, which leads to an educational pedagogy which overemphasizes ‘learning by doing’ without a proper understanding of either formal theory or an understanding of what you ought to do. Rather, I am a proponent of a solid liberal — and not just a vocational — education for everyone according to their abilities. Perhaps the final product reflects this.

Very many computer manuals are merely an organized collection of features, along with descriptions on how to use each feature. This material-and-efficient-cause emphasis is rather dreary, and the publishing industry has a glut of computer manuals that do this. Rather, I attempted to provide formal and final causes of each feature, answering the questions what is the nature of this feature? what does this feature do? how does it relate to the larger scheme of things? and most importantly when ought you use the feature? I also thought it was important to include links and references to authoritative sources for the features, so that a novice administrator at least has a basic understanding of the big picture. A discussion of when something ought to done is shown by this example:

Generally, you ought to create a new user account for each person who will administer the PoliWall. Every person with administrator duties on the PoliWall should have their own username and secret password, and you should assign each user account to one and only one person. No accounts ought to be shared. Each person, when they get a new account, ought to immediately change their password, and never disclose the password to anyone else.

Since the PoliWall keeps extensive and precise records of all its activity, including the actions of administrative users, these personal user accounts add a level of security and accountability, and helps prevent misunderstanding and fraud.

or here:

When you assign High Quality of Service, the PoliWall will give priority to outbound traffic to your selected countries.

High QoS may be useful when:

• The percentage of your used network bandwidth tends to be high on average. Most Internet traffic tends to be bursty, and so high QoS is usually of little benefit.
• Only a small amount of your traffic is given High QoS. If everyone has high Quality of Service, then no one does.
• Much of your low-priority traffic consists of extensive data transfers that would otherwise take up much of your bandwidth for long periods of time.

Internet technology, at first appearances, is a bewildering collection of acronyms such as IP, ARP, DNS, SMTP, HTTP, NTP and so on. But it has a rational hierarchical structure, and understanding this structure makes the administrator's job much easier. Very many of these acronyms are merely individual species within a common genus, and once you understand the common features of the genus, then you can deal with all of these species in a simple common manner. Once you understand that, for example, browsing the web or sending email are implemented in a common manner, you can extend your knowledge to hundreds of less familiar services. I thought it was important to include a list of the most common Internet services, despite the fact that it took several precious days of writing: an administrator browsing this list may find that it prompts his memory, so as to avoid possible configuration problems.

There is one feature of the manual that I thought was very important, but I was never able to elaborate it well enough to make it good enough for inclusion: this was a meditation on computer security in general. This was so wide of a discourse — ranging into moral theology and world politics — that it went far beyond the bounds of a simple manual.

---

Unfortunately this work — which I poured so much of my heart and effort into — is hardly suitable for my regular readers. There is room for a thousand improvements. But perhaps this is applicable: “their prayer shall be in the work of their craft, applying their soul, and searching in the law of the most High.” (Sirach 38:39)