Sometimes it is more difficult to revise than to begin
fresh.
As I work on revising our existing documentation into DITA,
I am often frustrated by the topics we have. Topics that written years ago are difficult to categorize into concept, task, or
reference. I find that I need many revisions to complete the job.
This is the process my team uses, with the Inbox section as
an example. Another writer and I worked on it together. We thought it
would be simple. We were wrong.
1. We read the current information.
We familiarized ourselves with it and looked at the order it
is presented in. I like to use the PDF version because I can put comments in as
I read through.
Inbox only had 6 topics, and seemed easy.
2. We brainstormed using the UI.
We created an outline by asking ourselves questions. What are the concepts the user needs to know? What are the
tasks the user can do? What references does the user need to complete the
tasks?
3. We inserted current topics into our outline.
We found that our current topics were long, and contained
multiple DITA topics. Usually task and reference were included in one topic.
Sometimes all three DITA topic types were in one of our tasks. We broke the
topics apart, looking at pieces.
4. We critiqued the remaining information.
Was it necessary? Was it needed but in the wrong place? Was
there a better way of presenting the information?
We found information on Inbox Preferences, but have no
preferences from the Inbox. Any preferences are adjusted in User Preferences.
Since the information was duplicated, we referred to User Preferences from
the Inbox Overview and in tasks associated with the preferences.
We were also able to delete a column of a complicated table
by adding one word in the DITA task.
5. We wrote new topics, and completed partial topics.
We found that the previous writer tried to use one topic to
tell the user everything about the Inbox. Some tasks were mentioned on one
line: You can forward your messages. Some tasks were missing all together:
Delete messages. It seemed simple, until we realized that some messages cannot
be deleted.
6. We had a new user review it.
We have a writer on our team who is new to the product, so
we asked her to read it and give us her thoughts. She had good feedback on
missing pieces and the order of topics.
7. We fine-tuned the topics.
We made sure that the metadata was in place, including short
descriptions. We also made sure the topics were included in the DITA maps and
index.
Revising took much longer than writing fresh. If we had
discarded the information that we had in the old topics, though, we would have missed valuable details. By working this way we captured the those details and
organized the information in a clear manner.
We finished with over 20 topics. These topics are
focused on one subject or task. They complete users’ immediate need. The Inbox
chapter is now true on-demand help.
