66

I have added a question in my answer to iTextSharp - when extracting a page it fails to carry over Adobe rectangle highlighting important info

I don't want to sound frustrating, but I would really love to hear why so many people always copy bad examples instead of using the examples on the official iText site (Java, C#) or from the book. We aren't hiding the documentation. What can we do to take away the perception that there's no documentation? What can we do to fight the abundance of bad examples?

I'm the original developer of iText. I'm also the author of the "iText in Action" books. In other words: I know what iText is about. I admit that iTextSharp - when extracting a page it fails to carry over Adobe rectangle highlighting important info isn't an exact duplicate of questions such as:

However, the nature of the problem is always identical: instead of reading the official documentation that clearly explains why PdfWriter shouldn't be used and why PdfStamper or PdfCopy are the better solution, people always refer to bad examples published online by people who aren't affiliated with iText in any way.

Is there a way to close a question with a friendly version of RTFM? If not, would it make sense to add this as a reason when voting to close a question. I've thought about "duplicate of", but losing an annotation (iTextSharp - when extracting a page it fails to carry over Adobe rectangle highlighting important info) is different from losing rotation (How to keep original rotate page in itextSharp (dll)) is different from losing page size (Itext pdf Merge : Document overflow outside pdf (Text truncated) page and not displaying) and so on... Only the cause is identical (not reading the official documentation, but instead copy/paste of a bad example).

18
  • 8
    We have a few examples where we create cannonical questions and answers to common questions or RTFM ones. Examples: RegEx, C# null reference exception. Remember though that not everyone may applaude such approach: meta.stackexchange.com/questions/228822/…
    – rene
    Commented Apr 24, 2014 at 6:40
  • 2
    So: the correct solution would be to create a Wiki (for instance summarizing the important stuff in chapter 6 of my book), but the most efficient solution would be to create a general question (covering the different aspects of the specific questions) and providing an answer that can be used to mark specific questions as duplicate. Is that a correct interpretation? Commented Apr 24, 2014 at 7:10
  • I've put it on my TODO list. If you create an answer based on your comments, I'll approve it. Commented Apr 24, 2014 at 7:28
  • 3
    IMO that entire paragraph you linked doesn't really belong in an answer (although some variation of the first part can probably be okay, if you change the tone from enquiring to informing) - answers should answer the question, perhaps provide some links as additional resources, and maybe point out some best practices, not ask questions. That paragraph would probably be fine as a comment on either the question or your answer. Commented Apr 24, 2014 at 8:27
  • 4
    Your problem reminds me of w3schools.com versus w3fools.com
    – Dónal
    Commented Apr 24, 2014 at 10:47
  • 10
    "instead of reading the official documentation that clearly explains why PdfWriter shouldn't be used and why PdfStamper or PdfCopy are the better solution" Then why does PdfWriter even exist? Even more so, because if I were looking to write a friggen pdf, the first thing I'd latch onto would be something called PdfWriter Signed, Genuinely Confused
    – user1228
    Commented Apr 24, 2014 at 13:14
  • 1
    @Will That situation is extremely common when something has been deprecated and will be removed in the future. Don't know if it is the case here, but I expect PdfWriter is the original, and is less functional than the others - and that it still exists only for compatibility.
    – Izkata
    Commented Apr 24, 2014 at 14:31
  • 22
    You do have to keep in mind that SO is a strong attractor for programmers doing it wrong and not reading the docs. We never hear from those that do it right. So maybe the problem isn't nearly as severe as you think. Yes, you ought to write a reference question so you can simply close as duplicate. Commented Apr 24, 2014 at 15:20
  • 1
    PdfWriter is the class you use to create documents from scratch. You can import pages from existing pages, for instance scaling them to thumbnails. Scaling and tiling ("N-upping" a document) are also common use cases for which PdfWriter is useful. However: if you want to copy documents, you should use PdfCopy. If you want to stamp stuff on a document, you should use PdfStamper. Commented Apr 24, 2014 at 15:53
  • 11
    @will When you go to lunch and you get soup as a starter, you take your spoon to eat it, you don't take your knife or your fork although they are also on the table. Your question sounds as: why are there forks and knifes on the table when they serve me soup? In reality, spoon, fork and knife each have their function, just like PdfWriter, PdfCopy and PdfStamper ;-) Commented Apr 24, 2014 at 15:55
  • 1
    What do you think your users are searching for before they post questions on SO? perhaps the seo on your docs isn't quite right so they aren't finding answers to their questions easily. Perhaps when you get rtfm questions gently ask the OP what they searched for and see if its turning up the right kinda stuff. Often (but not always) with rtfm questions its not that the OP didnt look its that they looked in the wrong places. Its the core reasons duplicate questions still get search indexed, they act as an oracle for what the op origionally posted
    – undefined
    Commented Apr 26, 2014 at 14:58
  • 2
    In many cases people ask questions like this because the manual is too extensive or poorly written. If you see a lot of questions like this on a topic where you wrote the manual, I'd suggest is might be constructive to consider if the manual needs improvement. For example, you might take a look at the accepted answers to such questions. And if you yourself answer the question and your answer is not accepted, that's another sign that you could be helping your users better than you currently are.
    – Warren Dew
    Commented Apr 26, 2014 at 23:46
  • 1
    The OP, user3566645, wrote: Why read a book when I can google the exact function I need that is working. I can return the question: why write a book, when people are too lazy to read it? My first book was a best-seller and I was allowed to write a second edition (that only happens with good books), but now that I know that people aren't interested in good documentation, why would I bother? @WarrenDew, I hope you understand that this is cynism, but also that there is less and less incentive for authors to write good documentation with people like the OP, user3566645. Commented Apr 27, 2014 at 12:30
  • 1
    @BrunoLowagie I understand the frustration. I think perhaps there is more than one kind of documentation that can be useful. There are reference manuals, there are tutorials, and there are recipe books, and a lot of people come here looking for recipes, not manual information. Now yes, some people want recipes because they are insufficiently patient to read a manual, but that's the nature of our industry, and ultimately providing recipes is what Stack Exchange is all about. Also, books are being replaced by web manuals which are more easily updated and more easily accessible from Google.
    – Warren Dew
    Commented Apr 27, 2014 at 18:19
  • 1
    @BrunoLowagie (sorry for the late chime in here) but as I said earlier and was said above, Google is the standard programming manual for many, many people, especially people that ask questions on SO. This is a human problem and hunting and pecking at one-time user1234's will just lead to frustration. Instead we need to attack from Google's perspective. Community Wikis are a great start, and like I said, if I get time I'll try to write a few. If you're interested, I'd also like to offer some of my spare time to help add more .Net documentation to the codebase.
    – Chris Haas
    Commented Apr 30, 2014 at 13:22

3 Answers 3

37

I'll answer your basic question here:

Is there a way to close a question with a friendly version of RTFM?

And the short answer is: Yes

You could create a canonical question with an answer. That question becomes the close as duplicate target for questions that have an answer in the canonical post.

Examples of such posts are:

The concept of so called Community Wiki is also explained in the blog post Putting the Community back in Wiki and I like this quote:

we’ve turned Community Wiki back into something that you can choose to use in cases where it lets you work together to create something wonderful

The Steps towards a canonical question

If you have read this far, don't run off now to post your question and answer.

  1. Improve the tag wiki
    It could include links to a few frequently asked questions and in the end also the link to the canonical question. This helps your peers to find the question.
  2. Have some pre-cooked comments ready to point new users to the tag-wiki. This helps both new and regular users to read that stuff (despite that software engineers are not good at reading stuff)
  3. Organize some regulars in a chat room to gather samples of questions and discuss topics that should go in the canonical question. This helps the sub-community to learn the mechanics
  4. Post on meta your intentions. Most important to see if the community at large supports your case.
  5. Make sure a moderator knows about it. This is needed to prepare for the launch so a wiki lock can be applied on the question.
  6. Prepare your question and the answer off-line in collaboration with your peers (For the regex post a Github Gist was used)
  7. Post your canonical question and answer.
  8. Start closing questions against the canonical question.
  9. Improve and update the canonical question and answer.

This sums up the process.

Does this mean that every question tagged can now be closed as a duplicate? No, certainly not. The other close reasons still apply. Overly broad or opinion based questions should still be closed against that reason. If and only if the question is answered by the canonical question closing as a duplicate is OK.

13

It is possible that the user was too lazy to read the manual. It is also possible that he didn't know about the manual, didn't find the relevant section of the manual, or didn't understand that section.

Closing a question is appropriate if the asker is simply lazy. It is not appropriate in the other cases, and therefore RTFM should not be a close reason.

To adress all these cases, an answer to such a question should point the user to the relevant section of the documentation, promoting awareness of the existence and usefulness of that documentation.

1
  • 4
    Just today I was so tempted to answer such a follow-up question with "Did you know that blue text on SO are hyperlinks, that you can move the pointy thingy on screen on top of it, and if you click one of the buttons on the box thingy you use to move the pointy screen thingie, a new page of text will magically become visible?" I restrained myself, today. I'm so proud of myself.
    – Jongware
    Commented Apr 25, 2014 at 17:39
11

My first Meta SO answer, be gentle ;)

The more important part of questions like the ones you refer to is usually a bit more obscure: either a lack of understanding of the concept to begin with, or a request for assistance (hopefully) after some failed attempts due to inexperience or simple misunderstanding.

I can usually solve my own problems by reading old postings (whether SO questions, blogs, etc. Generally non-interactive towards me.)

When I actually post a question to SO, I'm usually in a spot where I'm faced with either lack of sufficient understanding of the problem; the previously found answers are either contradictory or neither work; or I've already exhausted every option that I saw (and did not know about alternate solutions)

In those cases, pointing towards a non-specific information source (which, if properly documented, can get quite big) feels like a generic reply to a very specific question. It's similar to a helpdesk referring to the dumbed-down troubleshooting guide at the back of a booklet where you have to verify the most rudimentary things.
Even if it isn't like that, it feels like not being acknowledged. I worked on a technical helpdesk, and one of the things that improved user ratings of us dramatically was removing the 'global wiki' because the agents kept referring to it instead of helping the user when a single sentence would've sufficed.

However, I do agree that this only applies to specific questions. Broad or vague questions are easily answered by reading the documentation. But we already close questions that are too broad; I suspect this is for very similar reasons.
Furthermore, I'd expect someone to have consulted the official knowledge repository of the tool in question before posting a question. So for questions where the asker clearly did not read up on the subject material, I can agree. But this is usually already solved by the community. If reading the manual is such an obvious solution, people will mention it. If the documentation gets mentioned rarely, that is probably indicative of people generally not using the documentation.

It'd also be a valid response to those questions where you realize the asker fails (I mean that without any derision) at grasping the core concepts; things that are way below the level of the problem he's trying to solve.

But adding this as an accepted closing of a question? I fear this will be overused. In the current setup, someone can still link to the official documentation. Chances are that most people answering have consulted that documentation, since they know how things work.

And without trying to sound cynical; if there is a noticeable amount of people who do not refer to your official documentation and prefer to rely on their own snippets, that's a matter of either people doing what they like best (regardless of your documentation quality), or specifically not liking the documentation when they tried using it in the past.
I don't think this is something you can really change without forcing people to follow a more strict guideline on how to solve problems.

Edit

During the comment discussion below, I realized I can maybe sum it up more concisely:

SO allows people to give different and varied answers, and the preferred one(s) will be upvoted the most, and likely marked as the answer. But by closing questions beforehand, purely if someone has made some documentation on it (where would you draw the line?), you're preventing this from happening, and people will not get the chance to see the alternate solutions to a question. Even from the lesser answers, I have on occasion learnt something (even off-topic). It seems counterproductive to limit this type of community interaction.

5
  • Reading your answer, I realize that the question was somewhat wrong. The person posting the question assumed that he had read the documentation. Unfortunately, he chose bad documentation over the official documentation. The fact that there's so much bad documentation about iText is probably a result of the way some developers treat iText: they prefer obsolete forks over the official version because of license politics... Commented Apr 24, 2014 at 11:47
  • If 60% of a user base refuses to work with a specific version or an information source, it stands to reason that 60% of the answers will not use that version or source. It's no exact math, obviously. I think the 'non-official' answers you refer to are just a symptom of developers doing things in a way that seems best for them. I'd rather not take that freedom away from developers. Yes, you have to sometimes reel them back in when they've gone too far off base, but we start seeing what is actually used, and how it is used. Survival of the fittest development process, shall we say? :)
    – Flater
    Commented Apr 24, 2014 at 12:03
  • And the result is: an abundance of crappy PDF documents... iText is like a knife: you can use it correctly, or you can use it to cut your fingers. Plenty of developers prefer to cut their employers' fingers ;-) Commented Apr 24, 2014 at 12:06
  • 1
    But the quality of the documentation is important. Maybe for iText, it would be a valid response. But it doesn't automatically apply to all official sources. SO allows people to ask a question to the community of developers. Given how crowds work, if most developers have decided to not use the documentation, the answers (and upvotes) wil reflect that. "It's in the docs." is still a valid answer to give. But imo, not a valid close reason. A developer of tool X could actively prevent anyone from solving a problem with tool X with an improved implementation/quickfix of it; for example.
    – Flater
    Commented Apr 24, 2014 at 12:55
  • 5
    Maybe analogous: jQuery has a decent knowledge database. Yet many questions arise on SO that are easily answered by referring to that site. The people asking the questions are usually having more issues with understanding DOM traversal than understanding a specific function. That kind of information is not that readily available on the jQuery knowledge base, since it partially relies on CSS selectors, which predate jQuery. Unless you already know what specific topic you should read up on, the knowledge base can't help you, while SO has a much better chance of getting you on your way.
    – Flater
    Commented Apr 24, 2014 at 12:57

You must log in to answer this question.

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