Re: Assertions in Mathematica?
- To: mathgroup at smc.vnet.net
- Subject: [mg113511] Re: Assertions in Mathematica?
- From: "Sjoerd C. de Vries" <sjoerd.c.devries at gmail.com>
- Date: Sun, 31 Oct 2010 05:20:41 -0500 (EST)
- References: <iaj4ob$n70$1@smc.vnet.net>
I'm afraid I have to strongly disagree with your opinion (rant) on Mathematica's documentation. Though the docs are still not perfect, I usually find within a few clicks what I'm looking for. I'm actually rather fond of the documentation as it is now. The mixture of overview pages, tutorials, function doc pages, crosslinks, and the fact that doc pages are 'active' is very effective in my humble opinion. Access to the docs in function browser, book, and doc centre form is nice as well. Navigating around is extremely well done. There are some lingering issues, such as the occasional lists of "typical" option values listed on some doc pages instead of listing *all* possible option values, and the use of the same option name in completely different functions (like "Method") which often makes looking up the specific option doc page useless. And indeed, some options are only explained in the examples instead of on the formal section of the doc page. Peace -- Sjoerd On Oct 31, 8:10 am, kj <no.em... at please.post> wrote: > Thank you all for your comments and suggestions. The Hold* setting > was indeed at the root of the problem. Thanks also for the advice > to become familiar with Mathematica's evaluation sequence. > > Regarding the docs, I still think it is Mathematica's worst feature, > by far. Given Mathematica's general excellence otherwise, and the > fact that the main weaknesses of its documentation have not changed > one iota for the ~20 years that I've used Mathematica, I conclude > that these weaknesses are absolutely intentional. In other words, > more than just objecting to Mathematica's documentation, I object > to its long-standing *philosophy* of documentation. > > This philosophy centers on the imperative to avoid formal specification > as much as possible, and cover over this shocking omission with a > few laconic examples. > > I don't know why the makers of Mathematica insist on this form of > documentation. Maybe they perceive formal specification as a threat > to their intellectual property. Or as a threat to the freedom of > their future software development (since documenting a feature > thoroughly may be interpreted by outside developers as a commitment > to those details in future releases). Or maybe they believe that > users of Mathematica are too mentally feeble to read documentation > that goes beyond a few brief (and hopefully "*neat*") examples. > Or maybe all of the above. Whatever the reason, the fact remains > that, when it comes to the *content* of its documentation (as > opposed to its presentation), Mathematica is third-rate at best, > which is scandalous for software as expensive as it is. Even > open-source code like the standard Python or Perl libraries have > documentation that, even though it is largely produced by unpaid > volunteers, is vastly superior, content-wise, to Mathematica's. > > Mathematica's documentation is the reason why I never recommend > Mathematica to anyone. I just can't do it in good conscience, even > though, in many other areas I consider Mathematica the gold standard. > Yes, I use Mathematica myself, but that's because I've already > "paid the price" of countless frustrating hours of blind trial and > error to figure out what the documentation omits and thus reach a > minimal level of proficiency with it. IOW for me the worst part > is in the past. I'd gladly give up using Mathematica for good in > exchange for getting back all that misspent time. > > ~kj