How to Write About Changing Contexts in Procedural Task Steps
© Ugur Akinci
In using software, the context changes frequently depending on the actions we take.
For example, when we click a command button, a new window might open.
Or when we select a specific option from a drop-down menu, the system may display a new dialog box in a new tab.
A new window, tab, or screen presents a new “context” of action, offering its own buttons, GUI components, and further action alternatives. That’s what we mean by a “new context.”
There are two schools of thought regarding the proper way to write about such context changes as a part of procedural task steps.
New Context as a part of the Same Step
The first approach mentions the new context right after the step action that brought it about.
For example:
1) In the Users window [CONTEXT 1], click New [ACTION 1] to display the New Users dialog box [CONTEXT 2].
2) Select the Visitor option button [ACTION 2] to display the Visitor Properties screen [CONTEXT 3].
3) Etc.
New Context as a part of the New Step (IBM Style)
The second approach mentions the new context in the NEXT step brought about by the action in the PREVIOUS step. In this stylistic choice recommended by IBM, every step starts by defining its own context so we know exactly where we are in action sequence.
For example:
1) In the Users window [CONTEXT 1], click New [ACTION 1].
2) In the New Users dialog box [CONTEXT 2], select the Visitor option button [ACTION 2].
3) In the Visitor Properties screen [CONTEXT 3], do this…
4) Etc.
We recommend…
We recommend the second (IBM) method since it creates lean procedural steps and TASK topics, ready for DITA-based structural writing.
RESOURCES
For more on this topic, see:
DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA
By: Laura Bellamy; Michelle Carey; Jenifer Schlotfeldt
Publisher: IBM Press
Pub. Date: September 30, 2011
