Do 'Read the man pages...' type comments and answers have a place on Ask Ubuntu?

Question

In consultation with the Ask Ubuntu Community I would like to have some discussion and ideally a firm policy on how we should deal with Answers or Comments that invite people to find their own answers in the man pages of the relevant application.

An example, drawn from Ask Ubuntu, is this comment which gives some hints about a script problem and then a requirement to read a man page:

Wrap your autofix command in a bash script, and call that script from your for loop. In the scrip you can control autofix's outputs, check it's exit status, trap segfaults, etc. Read man bash.

Are such hints to read even sections of a 5,223 page man page useful for the type of user most usually found on Ask Ubuntu? Please give your thoughts below and help us to formulate a policy for dealing effectively and kindly with this matter...

Answer 1

I think there are several factors in play here that should be considered.

I believe it's good practice to reference to the man pages for some questions that fits the right criteria, namely:

1. The question is about a terminal command.
2. The question is about the use of a specific identifiable command (e.g. ls).

In these cases I think it's recommended to explain where to find the asked functionality in the man (or even info) pages where relevant.

Optimally, the answer should include a quote of the relevant section of the man or info page, and then preferably a link to the Ubuntu man page for the relevant distro. In the case of ls on Ubuntu 22.04, this link should be included.

I have an answer that I think is a good example of referencing the info page for ls (because in this case, the additional description was in the info page, not the man page).

I also think there can be questions that are technical in nature (and fits the above criteria), where you could rightly say that if a user didn't even consult the man page first, it would qualify as lack of research. But this again would entirely depend on the nature of the question.

If the question is clearly from a novice user, trying to do their best using the terminal, then I wouldn't expect familiarity with man pages. But if the question is clearly from an expert user, involving advanced terminal options, then I would expect the user to have at least glanced at the man page as part of their research.

But this could very well be a gray area, as there could be some questions in between, where it's difficult to determine what could reasonably be expected from the user.

---

Finally, I believe the example @andrew.46 includes is a good example of what not to do. Since the question is more about generally getting some things to work properly (and thus I don't think it fits the criteria I just lined out), just referencing the entire man bash (without any more details given) is somewhat rude actually.

Conclusion

Answers or Comments that invite people to find their own answers in the man pages of the relevant application

These have no place on Ask Ubuntu.

An answer that point out that man foo, section about bar, and quotes relevant parts of it may be a good answer.

But this would be the way to do it.

Answer 2

Directing someone to a manpage is a good idea, but not if it's used as a way to avoid giving an answer to the user's question in the body of the answer.

Here would be some practices I would recommend:

• When writing an answer, all the information that actually answers the user's question should be in the body of the answer. If there are links to information on another site, or instructions to look up information elsewhere, they should provide additional information and not be required reading to understand the answer.
• If the entire answer to the user's question can be found at another location, then providing a link is a good idea, but the answer should also be transcribed, or included in the body of the answer as quoted text. If it is given as quoted text and the quote alone is not enough to properly answer the user's question without additional interpretation, additional text should be given in the answer to explain this.
• Pertaining manpages in particular, in addition to the above (not solely relying on information elsewhere) it may be a good idea not only to link to the manpage (Ubuntu has manpages.ubuntu.com so you can always link to them), but to keep in mind the user may be unfamiliar with manpages, and may benefit from some background to what a manpage is and how to use one ("teach a man to fish" style). This article is the most helpful official article about that I found with a quick Google but there may be others.

Some of this is already covered by pre-existing rules about link-only answers.

Answer 3

I would argue no in general.

AskUbuntu tend to have novice users that are probably not very familiar with either Ubuntu or the Terminal in the first place; they won't know how to interpret the man page they're reading anyway, so it won't help.

This especially applies if there's many relevant man pages, or there's no indication for which section of a man page. An answer that point out that man foo, section about bar, and quotes relevant parts of it may be a good answer. An answer that simply says man foo is probably not.

In addition it goes kind of against the spirits of comments; If we believe the comment is helpful, it's an (bad) answer. And we don't want that in the comment section.

---

Teaching someone to use man is, on the gripping hand, entirely fine. Explaining what man is, and how it can be used to find answer to a particular question is Good(TM). But that probably involves hilighting a section, and may not be appropriate for novice users that havent ventured into a terminal yet...

Answer 4

I would like to make a case that points out that a generalized, "blanket" approach (rule(s)) might be less constructive than hoped.

---

Recently I have contributed an answer that later had proved to be useful.

I had cut out time for it from my life at a time when I am incredibly overwhelmed with challenges of incredible volume and incredible consequences. In fact, my IRL challenges are so overwhelming that coming to AskUbuntu and successfully help others is a rare source of uplifting success in my life.

In my answer, I had hinted at that I am not currently in a state to delve deep into a solution; I just shared a hunch that was cheap to produce. After that hunch had proved to be right, I aimed to help further by directing the asker in a follow-up comment towards the relevant manual:

[...] glad to be of help. Now that it's verified what the problem was, if you want, you can research the options used / usable in fstab. Maybe there are options that could be useful for you. man fstab tells me that it may be the nofail option. Seemingly this might enable you to reactivate the line —while equipping it with this option— and then temporarily remove additional external disks at ease, without having to edit fstab each time.

I suggest that my conduct —considering the current low availability of my resources— had found the optimal degree of investment from both the asker, and from me.

I aim to show that directing users towards manual pages can have a legit merit.

---

My takeaway is: when aiming for any policy, consider the user experience not only of the askers, but also the life circumstances of the answerers.

Please aim for a solution that acknowledges and includes both.