Software Documentation Terms You Should Know As a Technical Communicator

Introduction

A software technical writer must be very familiar with software documentation terms.

Software documentation is a distinct specialty within the larger discipline of Technical Writing. It’s a world with its own rules, processes, and lingo.

Here are some of the terms you should be familiar with if you are thinking (highly recommended!) to start a new career as a software documentation writer:

Client-Server Architecture

A network arrangement in which a number of “Client” machines are hooked up to one or more “Servers” through which they receive documents, configuration files, application files, etc. In most software companies, technical writers work on client machines networked to a central server, all protected behind a corporate firewall.

Client

The work station, the PC, is the “machine” that is hooked up, networked, to a Server PC on the other end of the Client-Server network.

Light Client / Thin Client

The client machine has very few applications saved on it. A workstation computer that uses applications saved on a Network Server. That’s why “light clients” are usually small units (PCs) with no need for a large hard disk or processing power.

Server

The “big machine” at the other end of the client-server network.

For example, in a typical set-up, Microsoft SourceSafe would be kept not on the individual machines of technical writers but on the central server. When technical writers save the documents they are working on to the SourceSafe they save it to a network server. That way, even if their local “client” machine crashes and loses all its data, their documents can still be retrieved from the SourceSafe since network servers are backed up regularly.

There are many different types of servers including document and database servers.

Testing

All software is tested thoroughly by a team of testers before being approved for the final release to the market.

There are different types of tests, like “unit testing” which tests whether a single software component is working properly or not, and “system integration testing” which checks out whether different components of a software system are working well together or not.

There are “stress” and “load” tests that measure how well the software performs under heavy usage. Does the software break down, for example, when a thousand or 10,000 users login simultaneously? That would be found out in a stress/load test.

Quality Control (QC) or Quality Assurance (QA)

Two other terms are used to refer to different types and modes of testing.

QA is a comprehensive sort of testing in which testers measure the degree to which a product delivers what it’s supposed to deliver. Although they are used separately, in my personal experience, they both refer basically to the same process.

The distinction is that QA is usually regarded as a more extensive, global, and comprehensive review of a product’s market suitability whereas QC is generally regarded as a more limited, local, component-by-component examination.

Build

Software development is a continuous process during which the developers change, add, correct, and delete pieces of code all the time, on a daily basis, depending on the feedback they get both from the project management and also from the testing, marketing, sales, and other departments.

The software is compiled on a daily, bi-weekly, or weekly basis to see how the product works with the new changes incorporated. Each of such individual compilations is called a “Build.”

Firmware

Firmware is a piece of software that is burnt into the hardware.

For example, your microwave oven comes with firmware already embedded into its microchip. That’s how it knows when to start heating your pizza, when to stop; when to switch on the ventilation fan and when to switch it off; when to add another 30 seconds of heating time; what to do when you push the button that reads “TV Dinner” or “Popcorn” etc.

All cellular phones, VCRs, cameras, and every electronic gadget you can think of these days comes with its own “firmware.”

A technical writer who has to document such a gadget has to interact with its firmware and understand how it works.

Bug / Debug

A “bug” is a code error that causes the software program not to act the way it’s supposed to, or to just crash. “Debugging” is the process and method through which the code is cleaned from such bugs, repaired, and restored to “health.”

Specs / Specifications

“Specs” is a term you hear very frequently in a software environment although it’s not unique to computer industry.

Every industry has its own specs since the term refers to the detailed technical definition of a component, attribute or a function.

If, for example, you’re manufacturing alarm clocks, the “functional spec” of the clock usually includes the temperature range in which the gadget is supposed to work.

A “marketing spec” includes the end-user functions that the software product is expected to deliver to the market.

Driver

Driver is a piece of software thanks to which your computer can use peripheral hardware devices like printers, scanners, etc.

PCs that use Windows OS (Operating System) work with drivers that usually come with the ubiquitous “.dll” (Dynamic Link Library) extension.

If you are using a Mac, usually you do not need to download or install a driver. Usually, a Mac automatically recognizes your hardware and knows how to use it and that’s why some people would not use anything but a Mac. However, if and when you need to install a driver for a Mac, it comes as a “.kext” file.

Command Prompt

There are times when a developer will tell you to “pull up” your “command prompt” and run an “IP config” check to find out the IP address of your machine.

What she is referring to is the DOS-based text-only black-screen interface where you can type in various commands and either get system information or (if you’re a hard-core programmer) perform any kind of file manipulation and configuration task you like.

In this screen, you type in a “command” that follows the strict syntax rules of the “DOS Command” language. In return, your computer follows your command, performs the procedure you ask it to perform, and prints back a response.

You need to study and learn the basic “Command Prompt” commands before you can use this functionality.

A little bit of cyber history… This was the way how all file handling and system configuration functions were handled before the advent of the graphic interface and the Mouse. Back in those good-old bad/old days, there was nothing to click-on on your computer monitor. Whenever you needed your computer to do something, you just typed its command into the “Command Prompt” screen and hit Enter.

Someone said, “if the regular graphic interface is like driving a car with an automatic transmission, using Command Prompt is like driving a stick-shift.” I think that’s a wonderful and appropriate analogy indeed.

Flat-File

This refers to a database in which the data is kept in a text file instead of a database file. Every line of text corresponds to a “data record.”

The data components are separated by a text character like a comma or a tab (which is invisible unless you toggle on your paragraph marks).
That’s why this type of file is sometimes also called “Delimited Data File” or “Delimited Text File” since a comma, a tab, etc. is also known as a “delimiter.”

For example, here is what a flat-file of student record data may look like:

(Last Name,Name,Gender,Age,School,Overall Point Grade Average,Sports Code)
Johnson,Jamell,M,20,Univ of Maryland,3.8,B

The advantage of a flat-file is that it has a much smaller file size than a corresponding relational database file. You can email a flat-file much more easily. Anyone with a text editor can open and read a flat-file.

The disadvantage of a flat-file is that it is not easy to search anything in it, or manipulate and re-classify it, filter it according to different criteria, and generate reports from it.

This major disadvantage escalates to a near impossibility when the data records (that is, lines of text) climb up to thousands.

In my personal experience, such flat files easily get out of hand and become almost useless once the number of records goes over a thousand.