Posted on Leave a comment

The Many Forms of Documentation

When I tell non-progammers I’m a software engineer most of them ask about coding languages or mention something about HTML. They have this idea that programming is all code all the time. A lot more goes into programming than just code. Before writing any code an engineer needs to know what capabilities are already provided to him/her. This is known as documentation.

Documentation comes in many forms. You probably already know one. Dictionaries are the most basic forms of documentation. They exist for spoken languages as well as computer languages. They contain words and their definitions. Some even contain grammar information. The dictionaries for computer languages are often called specifications. They contain the reserved words and grammar definition of a language.

Every computer language has a specification. The Java specification is on Oracle’s website. The specification is the most important form of documentation for a language. It defines what can and cannot be written in the language. The specification also defines the syntax of the language. However, as important as a specification is, they are rarely referenced. Most are difficult to read and contain more information than the common programmer is looking for.

The most common form of documentation is a class or function list. This kind of documentation varies from language to language but all have the same basic information. They contain predefined classes, methods, and functions for use in code. PHP has an excellent function list with the ability for people to leave comments. Another excellent example is the Mozilla developer network. These types of documentation are useful because a programmer can use functionality which is already built and tested instead of having to build their own. Most of my bookmarks are to a class list for something. The Unity game engine actually includes a class list as part of its installation making it easier to find documentation while offline.

A third form of documentation is what I call tutorials. They go by many names, tutorial, how to, cookbook, et. al. They contain examples of how to do basic or complex tasks. These are useful when there isn’t a single function to accomplish a task, but you know it is commonly performed. Looking up a task in a tutorial often yields a simple example and information for more complex situations.

The last form of documentation I will cover is the forum. This kind of documentation is a little different from the others. People ask questions and others answer. It requires a community of people capable of answering questions. There are many forums about programming. The most popular now is stack overflow. What makes these work is the community. With so many people willing to answer questions it is likely there is somebody capable of answering one you might have. Over time the forum becomes a reference as more questions receive answers.

There are other forms of documentation like BNF and class diagrams which I may cover later. Until then, know the differences and purposes of each kind of documentation.