Powered by Max Banner Ads
© Ugur Akinci
|SUBSCRIPT||Ctrl + ”+”|
|SUPERSCRIPT||Ctrl + Shift + ”+”|
Technical Writing & Communication Tips, Tutorials, and Trends
© 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.
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].
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.
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…
We recommend the second (IBM) method since it creates lean procedural steps and TASK topics, ready for DITA-based structural writing.
For more on this topic, see:
DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA
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:
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?
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.
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.
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