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 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?
My rule of thumb is "the right information at the right time", especially in content that's supposed to be consumed on a …
6y ago
If you have a few exceptional use cases, they should be indicated as such when they occur. If all other cases relate to …
6y ago
People do not read the documentation through. They dip into a specific spot in pursuit of one instruction on how to acco …
6y ago
This post was sourced from https://writers.stackexchange.com/q/33597. It is licensed under CC BY-SA 3.0.
3 answers
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.
This post was sourced from https://writers.stackexchange.com/a/33599. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/33598. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
0 comment threads
0 comment threads