3

I am working on specifying documentation for a soon to be released SaaS tool.

Some parts of it are very technical and will require an in-depth explanation of how it works.

Conceptually I was breaking documentation into two kinds:

  1. Definitions, detailed explanation of how certain things work.
  2. How-to guide. This would cover the main use cases that we envision people using the product. It would outline a use case and then provide the steps that the user would take to accomplish their goal. It would also give some examples of how the product could be used.

I was initially planning on two separate documents, although from my experience, this doesn't seem common.

Another option is that I could combine them into the same document, which would look something like this:

Area 1 of the software

  • Definitions / lengthy explanation of how certain things work.
  • Use Cases
  • Examples

Area 2 of the software

  • Definitions / lengthy explanation of how certain things work.
  • Use Cases
  • Examples

etc...

What is the proper way to handle this?

3

I'm not sure about common practice for this area, but the main thing that jars with me about this solution is that you are repeating the same type of content twice, and splitting it. If it's the same type of content, then it should be together. Why not try splitting these categories into sub categories when talking about each area of the software. E.G.

Use Cases: - Area 1 - Area 2

It'll allow easier comparison between the areas for the user, without them having to scroll back and forth like a mad man.

1

I would recommend the book Developing Quality Technical Information put out by IBM Press.

It explains that you should write all of your documentation in short, focused articles that they refer to as "topics." In addition, so that it is easy to understand, each topic should accomplish one (and only one) of three goals:

  • Instruct step-by-step how to perform a certain task. ("Task" topics)
  • Explain background information that users need to understand tasks. ("Concept" topics)
  • Provide facts that support a task, such as syntax and restrictions. ("Reference" topics)

Implicitly, all of your documentation should revolve around "Task" topics that are simple, step-by-step instructions that explain how to perform the various actions that your users will be interested in. Each Task topic should also include the rationale for the action, as well as its appropriate context.

We've applied what we learned from this book for a couple of years now for a large, enterprise software application that we sell via SaaS and also for customers who want to run it on-premises. It has served us well.

One final comment about Task topics that may be relevant to you. We have found that there are two types of Task topics: basic Task topics and use case Task topics. An example of a basic Task topic would be something like "Creating a User" while a use case Task topic would be specific to a particular, common customer use case. It would explain the steps at a high level and would link to the basic Task topics for how to actually perform each individual step.

I would recommend starting out by identifying the basic Task topics that your users will need first, and write those. Once you've written those, identify gaps in understanding that users will have and write Concept and Reference topics to help them understand the system better. You can rinse-and-repeat as many times as you want as you add more basic Task topics. Eventually also you should write the use case oriented Task topics, but I think those are less important than having a good core of basic Task topics available to your users.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.