STC WDCB Winner

Categories

Our Sponsor


Enter discount code WRITER111 in the shopping
cart and save $50 at ...

Users Online

+ 7 Guests + 1 Bot

Unique Visitors

  • 613229Visitors TOTAL:
  • 813Visitors TODAY:
  • 1101Visitors Yesterday:
  • 10989Visitors Last Week:
  • February 15, 2013Since:

MS Word 2010 Subscript & Superscript Hotkey Shortcuts


 Powered by Max Banner Ads 

MS Word 2010 LOGO

© Ugur Akinci

SUBSCRIPT Ctrl + ”+”
SUPERSCRIPT Ctrl + Shift + ”+”
Share

How to Write About Changing Contexts in Procedural Task Steps


 Powered by Max Banner Ads 

© 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.

Context in Procedural Steps 1

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.

Context in Procedural Steps 2

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.

Reference

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

Share

Q&A: What is the difference Between a User Guide and a System Admin Guide?


 Powered by Max Banner Ads 

User Guide vs. System Admin Guide© Ugur Akinci

READER QUESTION:

I’m working on a software product that has a GUI. Currently, we have a user guide and a system administration guide.

The user guide mainly focuses on tasks that can be done thru the GUI; the admin guide mainly focuses on system maintenance and administration.

However, there’s no distinguishing line between the two guides.

The user guide contains tasks that must be done by administrators; the admin guide contains a few tasks that must be done thru the GUI.

So my teammates and I started to think maybe we can improve the structure of those two docs. We have 3 options:

  1. Divide contents based on user roles. If we define the users as those other than administrators, we will move some tasks requiring admin rights to the admin guide.
  2. Move all tasks that can be done thru the GUI to the user guide and we mark each task with a specific user right; hence, the user guide contains GUI introduction and tasks done via the GUI introduction.
  3. Create a quick start guide for GUI introduction; and the user guide will contain all tasks for using this product. The admin guide will contain admin tasks.

The problem is that we are not very sure about the difference between a user guide and an admin guide. So we don’t know whether we can just pick one of the options or think of an improvement.

Would you shed some light about the difference between the two guides?

Do you think we need to restructure the two guides in the first place? If there is a need, how would you restructure them?

—————————–

ANSWER:

The general distinction you’ve outlined between a User Guide (US) and System Admin Guide (SAG) is correct. In general, that’s how it should be.

But what these guides should contain and whether there is a need for both of them depends on a number of factors which I don’t know at this point.

Letter writing 4For example, if your users are also authorized to perform administrative tasks, then perhaps there is no need for two separate guides.

If, for example, a user has the authority to change the settings of the individual fields, what a drop-down list should display, or decide on the number of digits a password can contain, then the user would be acting like a system administrator. In that case a single composite and all-encompassing guide would be appropriate.

But let’s say you are serving two different groups of “internal” and “external” clients. If the “internal” clients consist of your system administrators who calibrate and configure the system before it is delivered to the “external” end-users, and if such external users are not allowed to change any system settings, then you would definitely need two separate guides (UG and SAG).

The fact that certain admin tasks need to be done “through GUI” does not in itself make the SAG a traditional “user guide.” System admins will of course use the GUI to do anything they’d like to do. What else can they use to access the system? The criteria should be the “user roles”, that is, the access level or authorization level of the person using the GUI and the repercussions of the changes made.

Usually the changes made by system admins impact all the users, whereas a change made by an individual user will impact only that person.

For example, creating a “performance report” or an “activity report” (just to give an example) would effect only the person who is creating that report and thus is something that you can describe in a User Guide. But to determine which rows and columns should be included in the report and how the report should physically look on the screen are system admin functions because such a decision will impact ALL the users who generate a report. In that case the topic of “How to Configure a Report” should be covered in the System Admin Guide and not in the UG – unless of course you would like to give your end-users the freedom to change the way a report looks or which rows and columns it should contain (which is usually a product management decision and not something that a technical writer can decide on her own).  I hope the distinction is clear.

E-Learning Technical Writing is Technicial TrainingI think your instinct that these guides should be based on user roles (Option 1) is a correct one. That’s how I approach the issue myself.

I’m not sure if I understood Option 2 since all functions, whether they are user or system-admin functions, are done through the GUI for a software product. But perhaps your telecom system has hardware components too handled by system admins. In that case you might need a “Operator’s Guide” to describe those hardware configuration procedures that need to be performed by system administrators.

Option 3 is a frequently used complementary method. Besides having a UG and SAG, it is usually very helpful to also deliver a “Quick Startup Guide” which contains a lot of diagrams and illustrations to help the end-user start using the product in a hurry. Once the basic installation and startup configuration is performed, the users can consult the UG and the system admins the SAG to perform more detailed and in-depth procedures.

Good luck! Ugur

Share