7

This is in reference to the recent PlotLegends -> “Expressions” question.

I filed a repot on this behavior with WRI tech support. A little later rcollyer posted an answer explaining it was new (undocumented) feature. This morning I received an answer from WRI tech support classifying it as a documentation issue.

I happen to think "documentation issues" are just as much bugs an code bugs, especially when they are as egregious as this one. But it might be confusing to tag such question with our current tag. What does the community think? Do we need a new tag such as ?

  • 1
    Where do you draw the line between a documentation "bug" and information that, for whatever reason, simply isn't included in the documentation? – Shog9 Aug 8 '14 at 15:07
  • @Shog9. I don't draw a line. I believe lack of documentation of features that users need to know about are serious bugs. There are sins of commission and sins of omission, but both are sins. – m_goldberg Aug 8 '14 at 15:27
11

I think we should not use the tag for inaccuracies in the documentation. It should be reserved for situation when there clearly is a bug in the software.

Reasons:

  • The tag is already a sensitive and high maintenance tag. It should serve a useful purpose, and we must not allow it to become an outlet for ranting or expressing dissatisfaction. People are looking at things like how may -tagged questions are there, and it's impossible to deny that how this tag is used on the site has an effect both on the reputation of Mathematica and the attitude of individual Wolfram developers who may have put in many hours to ensure things work well. Just look at the responses to bug-tagged questions and how many upvotes trivial answers get.

    A tag with such impact should be used carefully and I would strongly prefer not to start using it for much more trivial things such as documentation inaccuracies. Take for example this question: when I looked at it first, all I saw was that 1) someone claimed Get was not working as it should 2) it had the tag; so I assumed that Get is broken. People don't read carefully anymore unless there's a good reason to do so. Usually they just skim. In this case it will be very clear for experienced Mathematica users that Get does what it should (there's no bug), but the documentation is not phrased very well.

  • It's much harder to decide what is a "true bug" in the documentation, than deciding what is a software bug. The documentation needs to be educational and easy to understand first. Perfect accuracy is impossible for any similar software, all of them have edge cases which are either not documented explicitly or mentioned only in advanced documentation. The documentation will sometimes simplify things in en effort to be useful for everyone, new and old users.

  • Unlike software bugs: The documentation keeps getting updated inbetween software releases. It is very easy to report documentation problems, even anonymously: there's a form for this on the bottom of every documentation page.

  • Unlike software bugs: If the documentation is not clear or not accurate, StackExchange can help: someone will explain clearly how the function works. If there's a software bug, in the majority of cases we user's can't fix it.

Let's recount why we have the tag. Do the reasons for having this tag apply to documentation inaccuracies as well?

  • Software bugs are wrong behaviour. Something that worked before doesn't work any more. When the result should clearly be 2, it gives 5. For those of us who work a lot with Mathematica, it's important to keep these things in mind, especially if the problems are version-specific. I sometimes use this tag to look up problems and read once again how and when they occur so I can work around them. I usually remember that there was a problem, but I don't remember what it was exactly, or more importantly: under what circumstances and in which versions it occurs precisely.

    This situation just doesn't arise if the problem is an inaccuracy in the documentation.

  • Hopefully the tags will be useful for Wolfram QA as well. Given the big difference in severity between a software bug and a documentation problem, diluting the tag will make it less useful.

  • So you are after [documentation-bug] or something? – Kuba Nov 17 '15 at 8:55
4

I think it is appropriate to follow the logic that rm -rf explained here:

Simply adding along with should be quite sufficient with regard to clarity, and assuming we adopt the policy of no longer version tagging bugs we will have plenty of tag room.

  • 1
    Should we be more tolerant towards opinion when it comes to using bugs together with documentation than when using bugs alone? So far we have only used bugs when the bug has been confirmed. – C. E. Aug 8 '14 at 18:49
  • 1
    @Pickett Good question. I think there still needs to be community approval as we don't want every possible misunderstanding of the documentation marked as a bug. Nevertheless it should be more clear cut if the documentation says X will do Y and it doesn't. Let's try it for a while and see how it works out. – Mr.Wizard Aug 8 '14 at 18:54
  • This seems a reasonable way to go forward, but I still worry that those reading the question will not perceive that tag "documentation" and tag "bugs" are intended to be coupled. Also, would you support adding these two tags to the referenced question? – m_goldberg Aug 9 '14 at 0:44
  • Huh? Why is the mouseover text over the downvote button "This answer is not useful"? I thought we were supposed to vote based on whether we agree or not. Is this a documentation bug :P? Anyway, I prefer a solution with a separate tag. I think bugs is not a very good umbrella, as I feel it is not clear whether or not a documentation error should be called a bug. If you call them bugs and even tag them as such, somebody looking for documentation bugs will be able to find them easily, which seems like a strong argument in favor of tagging questions this way. – Jacob Akkerboom Apr 8 '15 at 15:54
  • But really we are thinking about "something like an error" in the documentation and we end up with bugs because we know bugs are a big thing in software and on this site. But I feel calling documentation errors bugs for that reason just dilutes the term bugs. – Jacob Akkerboom Apr 8 '15 at 15:54
  • @Jacob Meta sites are weird; yes, the convention is to vote up for agreement and down for disagreement here, despite the mouse-over. – Mr.Wizard Apr 8 '15 at 15:57

You must log in to answer this question.

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