What's in a Name: When Known = Unknown

[JoshuaBixby]

This is the fourth in a four-part series on the challenges of naming new features in software applications; particularly, the consequences when naming falls short.  The first part in the series looks at a case when the name of a new feature clearly and succinctly describes the behavior of that feature.  The second part in the series looks at that same case when newer yet functionality alters the original behavior of that new functionality.  The third part in the series looks at how the documentation has changed to addresses this altered functionality.  And finally, the fourth part in the series discusses what it all means to end users and developers.

When someone has been using a software application for a long time, say ArcGIS Desktop for 10 or more years, it isn't completely uncommon for a user to get set in his/her ways, maybe even a bit complacent.  Not only does this happen with the use of software, it can also happen with reading software documentation.  After all, if you have been using the software for more than 10 years, of course you know what the documentation says and exactly how features work, right?

It is around this time that RTM, STW, or maybe GIYF comments can start showing up in response to one's questions in forums, listservs, etc....  (I know, forums and listservs are so Web 1.0, but they are still workhorses for many GIS practitioners).  But what if you have read the manual, searched the web, and gave Google or other search engines the old college try.  Well, sometimes the real answer is WABM, and I think that is what we have here when it comes to in-memory workspaces and background processing in ArcGIS.

In looking over the first three parts in this series, I can't help think of the latest Errol Morris documentary, or at least the title of it:  The Unknown Known.  In many ways, I feel like the in-memory workspace and its documentation represents an unknown known.  Giving Esri the benefit of the doubt and assuming there is at least one developer or group of developers that truly understands how in-memory workspaces are supposed to work, we basically have a situation where the documentation has completely failed to communicate the information.  The in-memory workspace information is known within the cloistered walls of Redlands but it is unknown to people actually using and developing with the software.  From the end user perspective, it is an unknown known, or maybe an unknown unknown for some.

The unknown knowns don't just end with in-memory workspaces.  For anyone who has worked with Esri software, especially Esri Support, he/she knows only a fraction of the bugs submitted get publically published in ArcGIS Resources.  For example, there are 4 open bugs relating to in-memory workspace linked to my organization's customer number and yet none of them is findable in ArcGIS Resources.  It is one thing for Esri Development to have their own bug tracking system and that information not be publically published, but not publishing known bugs from the Esri Support bug tracking system creates lots of unknown knowns, i.e., Esri knows there is an issue with the software but that isn't being shared with users.

So what does this all mean or what is the importance?  Wasted time, reduced productivity, lack of confidence in the software, and more....  The cost of poorly documented information is borne by the end user, and unfortunately that includes me.  When the choice of GIS software is a personal one, the end user has the choice to explore and possibly choose to use different GIS software; but when the choice of GIS software is made for someone by an organization, the end user just gets to eat the lost time, productivity, and frustration of working with software that either isn't documented well or doesn't work correctly.  Unknown knowns undermine the potential of software and can turn new functionality into little more than marketing hype.

[curtvprice]

Although I'm glad it's there, background processing is a bit of a kludge to give desktop users simple access to what is basically an instance of ArcGIS Server geoprocessing through x64 arcpy.  You see this sometimes with error messages that crop up that report a geoprocessing client/server error. Background GP is a separate process so there is no way memory object can be easily shared between what is essentially desktop and server.

The biggest advantage I see to x64 background processing is that you can do vector overlays that consistently fail in 32-bit. Recent enhancements to the overlay engine that tile overlay processing under the hood have made it possible to do a lot bigger overlays that you used to. (My take on this a lot of time is if my overlays are so big they are failing, it may be better to rethink my analysis approach, if only for performance reasons. Bigger isn't always better.)

Arcpy.mapping talks to the 32-bit ArcMap object base, so x64 wouldn't be able to talk to a running ArcMap session. This all makes sense to me, though I suppose they should put some detail about this on the page about limitations of background processing.

I have been successful leaving notes for the help developers using the feedback button on the online help pages. These comments often go directly to the help author with minimal filtering.

[JoshuaBixby]

Background processing was just the example I chose to make a point that incomplete, or worse inaccurate, documentation leads to confusion and wasted time and resources for users.  In the case of open source software, the fallback is the source code itself when the documentation isn't up to par.  Unfortunately for closed source software, that isn't an option.  Documentation costs money, I get that, but the savings upstream from poor documentation have a cost downstream.  Whether documentation is good or poor, someone is paying for it, and I think Esri can still do better.

None of the examples I gave involved 64-bit Background Geoprocessing.  Are there additional issues when 64-bit Background Geoprocessing is installed?  I am not sure, and I didn't want to complicate the discussion by introducing 32-bit/64-bit interactions into the mix.  I agree, though, that 64-bit Background Geoprocessing offers some very real advantages over regular 32-bit geoprocessing, foreground or background.

I understand that executing code out-of-process, 32- or 64-bit, involves marshaling of resources that can require changes to code to make it all come together.  When changes are required and behaviors differ between code running in-process and out-of-process, it is nice to have it documented.  What really struck me as odd was how some geoprocessing tools, like CopyFeatures, behave exactly the same whether background processing is enabled or not while other geoprocessing tools behave different.

Looking at the in-memory workspace specifically, I consider it notable when something named "in-memory" isn't in memory anymore when background processing is enabled.  I think most experienced ArcPy scripters figured that out through trial and tribulation, but why make new scripters learn it the hard way as well.

[curtvprice]

And my point was that Esri has given us a direct path to provide suggestions to help article authors -- we should use it!

[JoshuaBixby]

A link to provide feedback does exist, as you point out.  You state you have used it, I have used it, and I am sure others have as well.  It would be interesting to know how much users do use it, or don't as the case may be.  As much as providing a link for feedback is a first step, there are other companies that went a step or two farther with their online documentation years ago.

Regardless of what one thinks of the content quality, the Microsoft Developer Network (MSDN) structure is quite a bit more robust than the structure of Esri's documentation.  For example, when looking up information on something SQL Server 2014 related, there is a link at the top of the page for "Other Versions."  When deploying and managing numerous versions of software within an organization, which I think is fairly common for larger organizations, it is quite handy to see the documentation from earlier versions via a simple link rather than searching on an entirely new subdomain like we have now between ArcGIS 10.3.x and earlier versions.

In terms of feedback, MSDN offers a "Community Additions" section at the bottom of pages.  The Community Additions section isn't just for people to provide feedback to MS about their documentation, but also for users to provide information to other users.  As much as I can start a new GeoNet post to share information I have learned about how an ArcPy method really behaves, I think having that feedback right in the documentation makes it much more accessible.