37

When is it correct to answer "Please, RTFM because this is what I'm doing to answer your question/comment?"

I must admit that sometimes I answer not formally correct questions (without MWE, which doesn't show any effort, ...), just like some other users, but I do so hoping that the answer encourage OP's effort in understanding it and LaTeX in general.

I also have to say that a lot of my answers are possible after reading/consulting package manuals or searching through TX.SX because my memory is not good enough to remember the big amount of TiKZ or tcolorbox options.

So, I don't feel comfortable when questioners make new questions in comments or editing the original which can be easily answered after a quick view to package documentation. I'd like to answer RTFM.

But being polite as we are in this site, I just politely comment and|or edit the answer, introduce a documentation reference or a documentation snapshot.

What's the correct behavior? After how many questions can we answer RTFM without breaking TeX.SX etiquette?

Update:

After David's suggestion: Of course I won't answer RTFM under no circumstances. But I think we should more frequently suggest to take a look at package documentation, even more if we know it's worth to do it.

| |
  • 13
    My take is : It is always OK to RTFM in the comments, never ever in an answer. – percusse Jan 21 '16 at 13:46
  • Generally, answering where you would see an RTFM mostly fit means you're encouraging asking such questions in the future. So it's pretty simple: If you want to keep the quality of the site high, don't answer questions that deserve an RTFM. What I do is look at how deep the question goes whether or not it can be answered by using a master reference. – M.A.R. Jan 21 '16 at 18:37
  • 2
    I think you could distinguish more in your question whether you are asking it is ever appropriate to use the specific phrase RTFM (I'd say never) or if you are asking if it is appropriate to tell people to read a manual (which is OK sometimes, and if also accompanied by an inline answer, always OK) – David Carlisle Jan 22 '16 at 9:39
  • 6
    Instead of telling people to read the documentation (even politely) it might be more productive to search for a duplicate on the site. I would bet that many RTFM type questions already have answers anyway. – Alan Munn Jan 22 '16 at 23:14
  • @Ϻ.Λ.Ʀ. on the theory that those people who post RTFM questions never do research ahead of time, it means they didn't look at other questions on Tex.SE, therefore one withholding of an RTFM is not that likely to encourage another one :) Hopefully. I am not very active here but on other SE site I just link to the "how to ask a good question" and I see you have an on-topic page as well, that's cool – JimLohse Jan 29 '16 at 2:05
  • 1
    No @Jim; it does make a difference if I tell my friend "hey, there's this TeX.SE where you can ask pretty much anything" versus "hey, there's this TeX.SE where you can ask anything but you have to make sure you've read the manuals first". – M.A.R. Jan 29 '16 at 8:57
  • a) it was mostly a joke, b) the use of foul language in the title sets up a tone that encourages humor and c) you must have a lot of friends tell them to stop it! But seriously, I think the people who do this that you did not refer to the site don't benefit from the RTFM. – JimLohse Jan 29 '16 at 13:12
  • 1
    Sometimes those manuals are hard to find (e.g. oberdiek) Newbies may not even realize they exist. – John Kormylo Feb 12 '16 at 18:34
  • @user49915 RTFM = Read the Fu...ing Manual. – Ignasi Mar 13 '19 at 8:55
  • I've seen a variant where the 'F' stands for 'Friendly' :) – morbusg May 8 at 8:36
  • @morbusg Read The Fine Manual is also common. – Marijn May 8 at 16:19
47

Almost every question here can be answered by reading a manual (or the documented sources) so mostly I don't think a "read the manual" answer is appropriate (and definitely not that particular acronym which isn't that polite in most versions of its meaning).

Sometimes, if I think the user really could have tried harder, I do mention the manual. If an answer starts off "As it says on page 1 of the manual...." then that is (I hope) an implied hint that perhaps the OP could have found that without needing to ask...

The issue about new questions in comments is really a different one. There, if it is just a "clarification" I usually amend the answer or reply as a comment but if it is really a new question, just ask the OP to ask as a new question.

| |
  • 1
    "Just one little detail, can you make this bold?; Ah, just noticed, head does not align, how fix that?" If it is a stream of details that needs to be fixed, one after one, i tend to get annoyed. – Johannes_B Jan 21 '16 at 9:42
  • 23
    @Johannes_B don't get annoyed, just don't answer, and ask the OP to open a new question (or ignore, you are not obliged to answer comments). – David Carlisle Jan 21 '16 at 10:47
  • 4
    Amen to your comment. By the way, @Johannes_B you are not even obliged to answer. – percusse Jan 21 '16 at 13:45
  • Being annoyed might be the wrong wording. On the other hand, if it really is just a small detail, i don't think opening up a new question is really necessary. That is where the Q/A systems comes to its limits. – Johannes_B Jan 21 '16 at 16:56
  • 1
    I think there's another case where giving a documentation reference can be helpful. Suppose somebody wants to know how to do X and I answer using something like TikZ or maybe I adapt their code to use a library they didn't mention or.... Sometimes I figure they may well want to tweak things further and I'll say where in the manual details can be found. For libraries this is sometimes obvious - but some libraries have a lot of pages, so not always. But for other things, it isn't always easy to find and specific references can make it easier to learn more about a new-to-me command or library. – cfr Jan 24 '16 at 1:50
  • 1
    Given that I'm not the only person I've seen ask 'where is this in the manual?' in comments, I figure this information really can be helpful. And there is also an implication that a series of follow-up minor-adjustment questions shouldn't be necessary. – cfr Jan 24 '16 at 1:52
  • @cfr I think manual references as part of an answer are a good thing, but the question I thought was about answers that just said "read the manual" or in fact just said "rtfm" I don't think these are ever really suitable for the site. – David Carlisle Jan 24 '16 at 2:05
  • I wasn't disagreeing with you as such. Only you implied that such references are primarily appropriate as implicit admonishments, but I think they can be valuable when no such implication is appropriate. I often include them when I certainly have no intention of communicating any kind of criticism for not finding the information, however subtle. (Doh! This is covered in footnote 345a on page 4576 in appendix G.... ?? Not really.....) – cfr Jan 24 '16 at 2:26
  • What's wrong with "Read The Friendly Manual"? ... ;) – 0xC0000022L Apr 23 at 16:24
38

Although telling people to the read the documentation can have a therapeutic effect on ourselves, it's not necessarily helpful to the questioner for reasons that may not be apparent to us. Here are some:

  • Not everyone reads English sufficiently well to make sense of documentation, even though with a couple of examples to get them going they can then figure things out.
  • Even if you are a native English speaker, the conventions of documentation writing which seem obvious and clear to those of us with a computer science or programming background may be quite non-obvious to those who do not come from such a background (and there are many such users of LaTeX).
  • Even if you are a native speaker and have a programming background, some documentation is just plain crappy and hard to understand to begin with.

    And independent of these reasons, if there is a "purpose" to be on the site it should be to be helpful to others on a voluntary basis. So if you don't want to help, don't help, and that's fine. If you want to help, help, don't practice behaviour modification. For some questions I think it's appropriate to point out that the question is answered on p. xx of the documentation, but only as a gentle reminder not as an admonishment.

And remember, as a wise man once described himself "turning the TikZ manual into reputation since 2011" just think of all those points you can get from reading the FM yourself. :)

| |
  • 4
    Good points. And one more, even being more or less fluent in english and programming, they don't now that documentation is in their system and can access to it as easily as texdoc .... – Ignasi Jan 21 '16 at 16:53
  • 4
    TikZ and biblatex have extensive documentation and you often have to know where to look or have an idea what to look for for very small (but important) changes. I think this is where people having fun making a graphic or tweaking a bibliography are enjoying to answer. Especially for bibliographies, this is often a one time deal and nobody should have to read the huge documentation. – Johannes_B Jan 21 '16 at 17:01
  • 6
    Why don't you speak English properly? googles admonishment – percusse Jan 21 '16 at 17:10
  • 2
    @Johannes_B Yes, a good point. The biblatex documentation is an especially good example, because although it is very extensive, it is designed much more a s reference manual than a user's manual. – Alan Munn Jan 21 '16 at 17:10
  • 1
    @Johannes_B I agree: reading the documentation is itself a skill that can take a while to learn. Trying to navigate the biblatex-chicago manual, for example, is very confusing, since it is really an appendix to the biblatex manual and intentionally does not duplicate material that is the same in both packages. – musarithmia Jan 21 '16 at 17:11
  • 4
    @percusse: youtube.com/watch?v=rxUm-2x-2dM – Paulo Cereda Jan 21 '16 at 17:16
  • 7
    does tikz have a manual? – David Carlisle Jan 21 '16 at 22:54
  • 2
    I have had invaluable help on tex.stackexchange with answers ( where I am still grateful for ) I could ( probably ) have found out myself but only after many hours, if not days, of study and trial and error. For me, and I believe the majority of latexers, LaTeX is an invaluable tool but not a topic of research. Having a background in programming I do provide MWE's when I have one. My point being: I don't think rtfm-ing people away is compatible with the daily practice of the site. – nilo de roock Jan 23 '16 at 9:54
  • 2
    Completely agree re. non-programming. There's some linguistic convention to it which I sort of understand a bit from reading manual pages, but mostly a closed book. I disagree about refraining from behaviour modification. Not because I think it's helpful for people to do this intentionally but because I think that any interaction may affect somebody else's behaviour so that the only way not to do this is not to interact. Moreover, if none of us interact, this will certainly modify people's behaviour in the end because they won't ask here if months go by and nobody ever interacts with anybody. – cfr Jan 24 '16 at 2:01
  • @Ignasi lately I tried for pkg in hyperref nameref zref; do texdoc $pkg; done on my Ubuntu. Not a single one worked. I was looking high and low to find out how to get texdoc to work, because on Windows it works beautifully both with MikTeX and TeX Live. But somehow on Ubuntu I don't get it to work ... querying the package manager, all attempts I came up empty handed until I used apt-file search zref and discovered texlive-latex-base-doc. If it's recommended to read the manual, perhaps texlive-latex-base-doc should depend on the docs? – 0xC0000022L Apr 23 at 16:32
  • 1
    @0xC0000022L One more reason to not install TeXLive using the distro package manager. See tex.stackexchange.com/q/1092/2693 – Alan Munn Apr 23 at 16:59
  • @AlanMunn yep, been reading that article today. There's just one issue I have with it. How do I verify integrity? Packages have that advantage. And there is a detached ASCII-armored signature alongside the ISO, for example, but when I look for the key that signed it on the site, I am coming up empty-handed. But yeah, I was starting a question earlier when a recommended "related question" pointed me to what I was looking for. – 0xC0000022L Apr 23 at 17:27
14

There's a big difference between an RTFM (even if that exact phrasing isn't used) and a supporting reference to the documentation. For example, "Section/Page n of the manual for the X package says you always need to load X after Y" is an attribution that supports the answer, whereas "If you'd read the manual, you'd know that X must be loaded after Y" is an RTFM.

The StackExchange network generally encourages the use of attribution in answers. This is more important for sites such as english or scifi where answers can easily become opinionated, and answers without attributions may be downvoted because they're unsupported.

On this site, an answer such as "you need to load X after Y" can be easily verified by trying it out. We also have users on this site who are part of the LaTeX3 Project Team, or have been involved with the development of TeX for many years, or who are package/class authors. This naturally lends weight to their answers, but only for those readers who are aware of this.

I often land on StackExchange sites through web searches. I don't have time to do the site tour or find out about the users on that particular site. I just want an answer to my problem. An attribution helps to validate the answer, but it also provides a next step for my search if the question is only similar rather than exactly the same as mine and the answer doesn't solve my problem or doesn't solve it completely.

So personally I don't view a supporting reference to documentation as a cry of RTFM any more than I view a link to a related question as a cry of "why don't you use the flipping search box". The key thing here is about correctly phrasing attributions rather than emphasis on teaching users to read the manual.


Here's an attribution for this answer ;-)

From "How to write a good answer" (section "Provide context for links"):

Links to external resources are encouraged, but please add context around the link so your fellow users will have some idea what it is and why it’s there. Always quote the most relevant part of an important link, in case the target site is unreachable or goes permanently offline.

| |
3

I rarely write RYFM in an answer to a question, but I will often give a URL for TFM and quote some relevant text. Even if you don't quote the text, it's a good idea to verify tat the information really is there and in an obvious location. Also check whether the relevant terms are in the index; often they are not. Alan Munn was being generous when he wrote

Even if you are a native speaker and have a programming background, some documentation is just plain crappy and hard to understand to begin with.

Some documentation doesn't even rise to that standard, and a polite request to read the manual can save you some embarrassment if it turns out that the information simply isn't there.

| |
1

Well, let me try to provide a perspective that I haven't seen mentioned much.

I've been using LaTeX since around 2000 or so. One would think that I know my way around. I have mastered several programming languages since that time, TeX isn't one of them ;) ... I'm the proverbial one-eyed among the blind, at best, when it comes to TeX et. al. And it's not helping that some colleagues, including those that introduced LaTeX for our documentation process know even less than I do.

I will definitely appreciate a link to a specific manual, a quote from it and all that. Even a gentle Read The Friendly Manual in the well-known acronym form won't offend me.

But if I have my MWE condensed down to half a dozen lines of \usepackage and put considerable effort (and time) into working out why something doesn't seem to work the way it should (in my opinion anyway), it's not helpful to point me to the manual.

Maybe I'm not the average user in my reputation range or whatever, but when I turn here, it's really because I am literally reading the manual or after I did my best to find a solution on my own (often including reading or at least skimming several of the involved packages' manuals and usually several Q&As here on this site), usually having put in quite some time already. And sometimes the fact that the answer turns out to be trivial can be attributed to the same reason rubberducking works or because I didn't really understand what I was looking for in the first place (you can't understand recursion before you understand recursion).

And what does the manual mean anyway when I have half a dozen lines of \usepackage? Which one ...?

A lot and I mean really a lot of the issues I came across with LaTeX came merely from the fact that:

  • Somehow I got the order of \usepackage wrong ... and somewhere this is probably even mentioned, but sometimes not. Sometimes in fact the questions, answers and the comments provide so much "between the lines" here on TeX.SE, that I would say reading the manual isn't an option when the sort of knowledge I am seeking is "floating around" somewhere else.
  • The package version for some particular package was wrong ... as an example tabu - seemingly a frequent offender - seems broken (cells no longer colored) in the more recent 2.9 version, whereas the older 2.8 that comes packaged on my Ubuntu 18.04 has no trouble. If I use just tabu alone I cannot reproduce the error I run into. But with those three or four dozen packages used in the project in which I get this interop issue, I see it immediately. But creating an MWE from that behemoth of a project is ... not fun, or quick to do. And it's also not what I am paid for when LaTeX is "just" used to create beautiful documentation for the actual product.
  • There is so much contradictory advice out there! And while reading the TeX book can be enlightening (as I realized as of late), for LaTeX a lot of the Common Sense™ seems to have evolved. And sure, that's nice. But I am still being recommended books from 2004 and earlier (e.g. here). LuaLaTeX and XeLaTeX were not around back then, if I'm not totally mistaken. The handling of all sorts of non-Latin characters (and the glyphs they are supposed to turn into) was a frequent thing I battled and it's gone with LuaLaTeX, but along with it I can also (it seems) throw out a whole lot of that Common Sense™ I picked up along the way. Oh well ...
    Fortunately for me as German native speaker the situation isn't quite as bleak. Numerous books on TeX et. al. are available in my native tongue. And yet some of them also don't touch sufficiently on points like the next one (IMO) ...
  • It's hard to make sense of the log files. They often look like a dog rolled over the keyboard to type it out and it's seemingly more an art rather than a science to know what you're looking for. Thanks to the TeX book I am finally learning how to better read the log file.

I found the comment on another answer here (and I am quoting, because comments are volatile) sums it up quite nicely (emphasis mine):

I have had invaluable help on tex.stackexchange with answers ( where I am still grateful for ) I could ( probably ) have found out myself but only after many hours, if not days, of study and trial and error. For me, and I believe the majority of latexers, LaTeX is an invaluable tool but not a topic of research. Having a background in programming I do provide MWE's when I have one. My point being: I don't think rtfm-ing people away is compatible with the daily practice of the site. (nilo de roock)

And after all, if TeX and its family were a trivial subject matter, we would not have a dedicated SE site for it, would we?

TeX is old. In IT terms it's comparable to Earth's age when life conquered land masses for the first time or so. The corpus of available documentation is vast. Some is actually hard to come by (yeah, TeX book ... I'm looking at you!). Some is outdated (Git, btw, is another good example of a complex tool where this is an issue), in other parts the TeX book can still be of help even today. Some conventional wisdom isn't even in any manual ... or I've been reading the wrong manual all along.

So to the experts "in the room" I want to say: Thanks for the help so far, please be patient and be gentle (but firm!). We, I, will get there! All things are hard until you master them ...

| |
  • Learning how to debug a LaTeX file is a long, slow process, probably never ending. But there's a wealth of information on this site. You might start by looking at the questions listed in the Debugging & log files section of the "Often referenced questions" here on meta. I gave a talk at a TUG meeting a few years ago on LaTeX debugging, and wrote it up for TUGboat. As for TeX being old, well yes, but it's quite stable; can't say that for much other software. – barbara beeton Apr 23 at 20:38
  • @barbarabeeton thanks, especially for the second pointer. And yes, I realize that this site contains a wealth of information, it's one of the points I wanted to get across. In fact I find that for certain areas this site contains more (or more useful) information than the reading of the M in RTFM could provide. It's why I think RTFM falls short of what would be desirable. That's why I decided to provide a slightly different angle as - so far - the one with the lowest reputation to offer one. – 0xC0000022L Apr 23 at 20:57

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .