How to Write an Effective Concept
By Sabra McGrew, SDI Information Developer
And Joan Celmer, SDI editor
Whether you write in DITA or another format, you need to decide what information in a concept is important to a user. Including only what the user needs to know eliminates unnecessary information, makes updating existing documentation easier, and reduces translation costs. The trick, however, is deciding what information should be included or removed.
There are four questions that a concept should answer:
1. What is it?
2. Why do I need it?
3. How do I use it?
4. What are my choices?
What is it?
I can’t tell you how many times I’ve read a concept, and I had no idea what the concept was about. It always helps to start with a definition, and if appropriate, an example of what you are explaining. Is it a process, function, feature, or your dad’s old sock?
Answer the question so that it makes sense from a user's perspective. Provide enough information so that the topic is helpful to the user, but don't include extraneous information that doesn't directly apply.
Example: “Feature X uses Y to adjust the behavior of Z.”
This sentence lets the user know exactly what this concept is about without the having to read through a bunch of text. The user can then decide if they want to read more.
Why do I need it?
When a user is reviewing the new information, they usually have a specific idea of what they need to accomplish or they want to determine whether the information will help them do something better. Essentially you are trying to “sell” the user as to why they need this feature, function, or process. You need to explain how the user can benefit from it.
Example: “Feature X uses the information gathered by Y to enable the servers to adapt to changing traffic patterns. If more traffic is sent to server A than it can handle, feature X reduces traffic sent to server A.”
How do I use it?
Explain how the user would use this feature, component, or process. How does the user implement this feature, component or process? Does the implementation require one or multiple tasks?
You also need to consider how this topic relates to other concepts or tasks. You might include links to other topics that a user needs to understand the implementation.
List the major steps that a user needs to implement this feature. This list aides the user in determining what they need to do overall. Be careful not to include an actual task in the topic because it might make reuse more difficult. You can make each major step in the list a link to a task topic.
Example: “To implement feature X, you need to do the following:
1. Configure feature X through the GUI.
2. Update N.
3. Restart the server.”
What are my choices?
Frequently there are several ways to implement the feature, component or process. Each choice has pros and cons that you need to explain to the user so they can make an informed decision. If there are several choices, create a table that explains each choice. You might consider creating a list of requirements for each choice.
Example: “You can use either static or dynamic configuration. Use static configuration when you must manually update the configuration tasks. Use dynamic configuration to automate the configuration tasks.
Conclusion
Making the documentation accessible to the user reduces frustration and allows you to focus on what is important to the user. While your particular product may have additional questions you need to answer, deciding what questions should be answered from a user perspective educes writing time, provides concept consistency, and increases user satisfaction.