As well as providing a concept for the software, good documentation will also provide a specification, detailing the specific characteristics and behaviors of the interfaces provided by your software. This part of the documentation details the contract that the user or programmer can expect to have when using the software.

The specification should ideally be the simplest part of the documentation to write, for the following reasons:

• It's literally in the code: The specification of behavior is contained within the code and its tests, usually making it quite simple to manually write up this information as documentation. However, if it is difficult to write, then that indicates an underlying complexity in your code and its interfaces that perhaps should be fixed as a priority.
• It's possible to automatically generate: There exist many documentation generators that either rely on static-typing annotations or comment annotations (for example, JSDoc). These allow you to generate documentation for entire interfaces via a CLI or build tool.
• It follows a fixed format: A specification will follow a straightforward format that is simple to author. It usually contains headings for individual endpoints or method signatures, and a sentence explaining each argument.

The overriding purpose of providing a specification is to answer specific questions that a user might have about the operation of your code:

The following is an example of a specification for a function called removeWords.

removeWords( subjectString, wordsToRemove ); 

This function will remove the specified words from the specified subject string, returning a new string to you. A word here is defined as a string of characters bound by word boundaries (). For example, specifying an "I like apple juice" subjectString  and ["app", "juice"] for wordsToRemove would remove only "juice", as "app" exists in the subject but is not bound by a word boundary. The following are the arguments:

• subjectString (String): This is the string that the specified words will be removed from.  If you do not pass a String type, then the value you pass will be cast to a String.
• wordsToRemove (Array): This is an array containing words that you wish to remove. A null or empty array will cause no words to be removed.

As you can hopefully tell, this specification is a purely technical explanation of a function's behavior. It tells the user exactly what arguments they must provide and what output they'll receive. When writing the specification portion of your documentation, the most important qualities to abide by are clarity and correctness. Be wary of the following traps:

• Not enough information to allow usage: It's important to provide enough information about your implementation so that another programmer, with no knowledge of your software, can begin to make use of it. It's insufficient to only specify types of arguments, for example. Provide extra information if the knowledge domain is especially obscure.
• Incorrect or out-of-date information: Documentation can easily fall out of date or be incorrect. This is why it's quite common to generate documentation automatically from annotated code. That way, the chances of information being incorrect or out of date are lessened considerably.
• Lack of examples: It's common to only list modules, methods, and argument signatures, without providing any examples. If doing this, the chance of confusion and pain is far higher, so it's always worth providing sensible examples or linking readers to more tutorial-like documentation.

The specification is arguably the most important part of your documentation, as it explains, in clear terms, the behavior of every part of your software's relevant APIs. Ensure that you take the same care and diligence when documenting your code as you would when writing it.