views:

68

answers:

2

Hey all,

As a software shop, we are well accustomed to delivering bespoke applications and solutions based on individual client requirements. For each system, we generally prepare the following documentation (with variations based on the specifics of the job):

  • Vision and scope
  • Requirements specification
  • Detailed design
  • Project specification

However, we have recently been working with another division in our company, who would like to resell one of our software creations as a product.

We are fine with this, and have implemented some informal procedures for controlling features and working towards an initial release. Up till now, I have been keeping an informal specification of the software using some diagrams, flowcharts, etc.

My question is, what has worked for you in terms of documenting a software product? We don't really have any experience with this, and I am completely confused about what should be provided. It would be nice to have something that can be shared with the division of the company that is funding this development, and it would also be nice to have soemthing that can form the basis of technical marketing materials (e.g. to present to architects at potential customer organisations).

Any suggestions/discussion is appreciated!

+1  A: 

Here's what you want.

Documentation is used in different ways by different parts of the purchasing organization. Each team that is using or developing on top of your product has different needs that you will need to take into account. One uber form of documentation will not serve the buyer very well. Here are four sets of documentation that you may want to provide.

  • User Manuals

    This is the manual used by any non programming/non customizing users of the system. I won't call them end users because some software has end users which are ultimately programmers. This is the group of people who are using your software (stand alone, embedded in Excel, web interfaces for managing content) in a day to day operational aspect and require clearly written instructions, COLORFUL pictures and a well considered index and table of contents that matches the different aspects of the system.

  • Training

Similar to the user manuals, training information should be colorful, well written and easy to refer back to (though training material does not have to be reference material). This should be written with the thought of an experienced trainer guiding the users through using the system. Training materials will include exercises and references to the user manuals if available. If your system has user manuals, you may want to consider creating a training procedure for this.

There are two different areas of training to consider - operational training and developer training. You will want to create different types of documentation for either audience if they exist.

  • API Documentation

If you are selling the source code to your product and it will be maintained and or used by other programmers then you will at the minimum need to provide API documentation. This will require a few items.

First your code should be well commented and a basic API documentation should be able to be generated by some sort of automated documentation program. This is the bare minimum that should be made available.

Second, you should provide useful UML documentation where necessary, ONLY if you think your audience needs this. For highly technical API's it's always better to provide this information.

Third, provide EXEMPLARY EXAMPLES of your code. This means that even though the inner workings of your code might not be best practice, you need to provide best practice approaches in all examples of code that you provide. NO HELLO WORLDS!

These examples should show code that works well in the current context, but also shows how it can be extended and to what extent it may need to be replaced when business conditions change. Technical software examples need not be purely technical!

  • Bulletins

As your product is updated you will want to provide your customers with updates to the API, and these can be provided in the form of bug notifications.

You will also want to set something up on getsatisfaction and linked in for your product so you can control the "customer portfolio" game. This means that if you have an established user base using the product, they should be able to get together to exchange information but you should also be the moderator of the topic if the community is small and intimate enough.

Shaun F
A: 

I agree with Shaun, who said, "Documentation is used in different ways by different parts of the purchasing organization".

More specifically, different people use documentation for different purposes, in order to perform different jobs. It's helpful to:

  • Identify what different people's tasks are, associated with your software
  • Determine what information they need in order to perform those tasks
  • Write task-oriented documentation, which contains the specific information for that task

Some examples of "tasks" (for wich you provide corresponding customer documentation) include:

  • Decide whether the buy the software: what are its benefits? what does it do?

  • Planning before deployment: what machines, other software, training, and hiring will be needed?

  • Installation: how to install

  • Using: may be several manuals (e.g. quick getting started, specific tutorials, big reference)

  • Programming: APIs etc

  • Maintenance: errors, logs, upgrades, ...?

Incidentally the above ideas comes from decades ago, when people printed documentation on dead trees. Nowadays, documentation may be:

  • Online (e.g. a web site)
  • Navigable (hyperlinks)
  • Searchable
  • Interactive (customer forums, customer support staff)
  • On-demand (e.g. you might write a "FAQ" based on whatever the frequently-asked questions actually are).
ChrisW