Creating Topics: Where do you Draw the Line?
By Eric Armstrong on Dec 03, 2008
It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways.
When you're looking at a page sitting all by itself, how do you know which parts really belong in a separate topic, and which parts belong together? That "bottom up" approach doesn't give you any useful "razors" to help you make decisions.
But if you look at things a little differently, things make a little more sense.
You may want to create an individual topic for one of several reasons:
- You want to link to a piece from multiple places (or reuse it).
- You want the flexibility to easily rearrange the sequence.
- That's all the user needs to know to answer a question.
- That's all the information needed to accomplish a goal.
(A) & (B) are driven by a top-down look at the information if you're a "waterfall" designer, or by inside-out refactoring if you're an agile-methodology aficionado. (C) is driven by the same considerations you use when creating a glossary--but with allowance for longer explanations. (D) is driven by user task analysis--which is arguably the most important part of the whole topic-oriented approach.
For a drawing program, you have material that describes colors. That's useful information when creating text, lines, or shapes. So it belongs in a separate topic so that you can easily link to it, if nothing else.
For a large volume of material, the best order of presentation tends to emerge only after you've written half of it. (A third, if you're lucky.) In that case, individual topics are more easily rearranged as you go along.
If the question is "What's a system", then the material that answers the question defines a topic. If you have "blue systems" and "red systems", then they would be related links, each in it's own topic.
- If it takes 10 steps to install a system, that's a task. If one of the steps has a couple of variations, and they each have many steps, then each of them becomes a task, and maybe the step in the main task provides guidance on which option to choose, with links to the subtasks. (Things are bit more problematic, though, if you don't allow links inside your topics. I'm not sure there is a good solution, in that case. You may be forced to make a longer topic that includes the subtask variations.)
Those are my thoughts so far, at any rate. What are yours?