: Where would I specify which user is required to run an administration command? I work with a software product that has over 10 major components. The administration of most of these is done

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)