Where would I specify which user is required to run an administration command?

Question

I work with a software product that has over 10 major components. The administration of most of these is done with the root user with one notable exception where they use a less privileged user for such purposes. In most places, the instructions specify the user, and may even include instructions such as:

su - lessPrivilegedUser
clustercommand --resursive --restart

However, yesternight I bumped into a set of commands that stop and start a service where the instructions did not include this information. Neither did the section one level up. So I requested the documentation team to make amends. To my great surprise, they responded with the result list of a search saying that the documentation already has this in 28 different places, asking me to confirm whether I am certain I want it included for the 29th time.

Q: Should the user be specified for each administration task in an administration guide?

Answer 1

Yes, always tell the reader which user to use

In material like this, there is no way to predict where the reader will start and if they have read any of the preceding material. If they ask themselves "how do I accomplish X" and you have a section named "Doing X", they're going to skip that other stuff. I've seen this described as the every page is page one model. It is very real behavior.

Another good reason to always and explicitly tell the reader what user to use is that (if the user is important) there are probably security implications if the reader uses the wrong user account.

If you are writing task-style topics with a prerequisites section, that is a good place to tell the reader which user to use. However, if your content has a lot of code/command snippets, you can also use a code comment. Using your example:

# As lessPrivilegedUser
clustercommand --resursive --restart

As a reader, I know I personally would appreciate that attention to detail. It also helps make your documentation safer. If the user is just going through your doc and copy/pasting and running commands blindly, they'll at least see that important note.

Answer 2

My rule of thumb is "the right information at the right time", especially in content that's supposed to be consumed on a topic rather than a chapter/book basis. Sure, this leads to some repetition but with the latest and greatest reuse mechanisms in doc tools it shouldn't be a problem.

I would probably place it in the requirements section of the task topic (if it's a task topic), or state it in a comments/requirements section in a reference-style table or list.

Answer 3

People do not read the documentation through. They dip into a specific spot in pursuit of one instruction on how to accomplish their task of the moment.

As far as the reader is concerned, therefore, Every Page is Page One. There is no rest of the manual. There is only this page. It is all I am looking at, all I am interested in looking at, and all I am going to look at.

If the information I need to complete my task successfully is not on that page, then as far as I am concerned it is not in the documentation.

The DRY doctrine only applies, if it applies at all, to unit that the reader actually uses. For instance, you would never invoke DRY to justify not including a piece of information because it was already in a manual for a different product that you released 10 years ago. DRY can only be applied to the context of use, and the context of use is the page, not the manual that contains the page, but the individual page the reader is looking at. Because that is all they are going to look at. Every Page is Page One.

Answer 4

If you have a few exceptional use cases, they should be indicated as such when they occur.

If all other cases relate to a single problem space (user privileges in this example), this should be indicated in an introduction and perhaps reiterated in another major section in case the user skips the intro.

Answer 5

If you have to specify it that many times, then it seems to me that I would put the information in an appendix and then for each set of instructions add a marker of some sort (text or an icon) that tells the person what login is needed at that level. For example:

• Task 1 [User]
  • instructions
• Task 2 [Superuser]
  • instructions
• Task 3 [Superuser]
  • instructions
• etc
• Appendix: Users
  • This is how a User logs in
  • This is how a Superuser logs in

Sometimes the docs team could use a snippet of text that is usable in multiple places while only being editable in one. But when that snippet is being used in so many places, I have to wonder if that's the best way.