Q&A: "What is the difference Between a User Guide and a System Admin Guide?"
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:
- 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.
- 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.
- 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.
For 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.
I 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
(Copyright-free photo by Alexander Naugh at Unsplash dot com)
