Tag: guidelines

Posted on by

How to Write Error Log Messages

error-log-messages-how-to-write

You know in Star Trek, when they’re looking into the Captain’s Log? I bet they also had an Error Message log for when things went real bad. You know, like when the Klingons actually won and took over the Enterprise.

Ok, so what’s this got to do with tech docs?

Well, it’s a roundabout way to look at error log messages. They don’t get much love, do they?

If you’re not happy with the quality of your error log messages, see if this helps.

How to Write Error Log Messages

Severity Levels

Error messages fall into the following categories: Error, Warning, or Information.

Define your log messages according to their severity.

  • Error – The error is severe. Immediate action should be taken to avoid the loss or corruption of data.
  • Warning – Action should be taken at some stage to prevent a severe error occurring in the future.
  • Info – An informative message, usually describing server activity. No action is necessary.

Checklist using Cause/Solution Format

Use a cause/solution format when writing the error log messages:

For example:

9968: No port defined for import.

Cause:

The server cannot detect a port.

Solution:

Contact Technical Support.

9969: Bulk import not supported.

Cause:

The server will not accept an import.

Solution:

Contact Technical Support.

9807: Ignoring large value for new_attribute_name.

Cause:

The value of the configuration attribute is invalid.

Solution:

Change the value of the configuration attribute. Refer to the Help files for the acceptable value range.

Checklist for Complex Issues

In some cases, you may want to provide more background details and list the steps to resolve the issue.

6696: Source Not Available

Description:

A Source is not available. Last monitoring query showed source is unavailable.

Cause:

The error occurred because of any of the following reasons:

  • Data source is offline
  • Data source is not responding
  • Network issue

Solution:

Do any of the following:

  • Bring source back up
  • Fix network issue
  • Bring source down.

… stay tuned for next week’s episode!

Posted on by

C# Namespace Guidelines

Let’s create some guidelines for documenting .Net Namespace.

For example, let’s look at the System.Collections Namespace. What do we notice?

Namespace – define the namespace using the following convention: System.Collections Namespace

Purpose – describe the purpose of the namespace, for example:

crone-park (33)

 

The System.Collections namespace contains interfaces and classes that define various collections of objects, such as lists, queues, bit arrays, hash tables and dictionaries.

Classes

We then identify the classes related to the namespace. For each, we identify it and describe its purpose. Use the correct case when documenting the
classes.

Note: it’s ArrayList, not Arraylist or arrayList.

Class Description

ArrayList – implements the IList interface using an array whose size is dynamically increased as required. Note how IList is spelt. Both the I for
Interface and L for List are capitalized.

BitArray – manages a compact array of bit values, which are represented as Booleans. True indicates that the bit is on (1). False indicates the bit is off
(0).

CaseInsensitiveComparer – compares two objects for equivalence, ignoring the case of strings.

CaseInsensitiveHashCodeProvider – Obsolete.

Structures

Next, identify the structure related to the namespace.

Structure Description

Dictionary Entry Defines a dictionary key/value pair that can be set or retrieved.

Interfaces

For interfaces, note the casing for IDictionaryEnumerator. I for Interface and D for Dictionary and E for Enumerator are capitalized.

Interface Description

ICollection – Defines size, enumerators, and synchronization methods for all nongeneric collections.

IComparer – Exposes a method that compares two objects.

IDictionary – Represents a nongeneric collection of key/value pairs.

IDictionaryEnumerator – Enumerates the elements of a nongeneric dictionary.

Use verb constructions to describe the purpose of each interface.

Posted on by — 8 Comments

How To Write Technical Documentation For APIs

One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.

An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.

What is an API?


APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia

Concept

An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.

An API can be:

  1. Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)
  2. Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
  3. Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
  4. Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.

For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.

“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.

API Guidelines

Here are some sites that offer guidelines and examples of API documentation.

Twitter’s API Documentation

Twitter has done a great job documenting its API and breaks out all the different component.

“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.” http://apiwiki.twitter.com

Tips for writing API documentation

What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?

FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API