9

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?

|improve this question

migrated from techcomm.stackexchange.com Feb 20 '18 at 15:23

9

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.

|improve this answer
  • 1
    Often it's good to put required permissions / privileges / user roles at the top of the topic so that if a user doesn't have them they can contact someone who does instead of wasting time trying to do it themselves. – Robert Lauriston Jan 31 '18 at 17:26
6

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.

|improve this answer
6

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.

|improve this answer
0

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.

|improve this answer
  • 1
    I'd tent to agree if this was say an install guide or a hardening guide where my engineers are going to follow the doc from cover to cover. However, the admin guide is pure reference. They have a problem, search for it and hammer in the instructions they find. They will not read a whole chapter, but will only perform that tiny subsection at the bottom of page 237. – Lefty G Balogh Jan 30 '18 at 15:01
  • OK. But can it be assumed that everything applies to a certain user and then you would specify the exceptional cases as you would when indicating that a certain feature is deprecated or added in a specific version? – David Vogel Jan 30 '18 at 15:06
0

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.

|improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.