[OpenLayers-Dev] Getting Help Faster: Minimize Your Code

[Christopher Schmidt]

Hi,

(Cross-posted to dev and users: please send all replies to the users list.)

Many times, users have come to me, or asked questions in IRC, related to
getting help with a particular behavior. Whether that behavior is a bug
or user error, there is one thing that you can do to make it more
likely that a developer will be able to quickly help you with your
problem. (In some cases, this is the difference between getting help at
all, and simply not receiving any.) I have never seen any situation
where this rule does not apply, and so I want to share it publicly with
the users and dev communities so that we can all learn from it, and
learn how to help each other more quickly and easily.

(Throughout this post, I use the terms 'developers' and 'users'. By
these terms, I mean "persons who have knowledge of the code inside of
the OpenLayers library" and "persons who have knowledge of using the
OpenLayers library, but not what is inside the library itself.")  

Minimizing Test Cases
---------------------

In order for developers to help fix a problem, they first have to
understand it. In order to do that, they need to understand everything
thati s going on in a situation where the problem is reproducible.
Oftentimes, the particular behavior is only existing in a certain type
of situation, or in a limited case that is not exploited by the commonly
used code. (In addition, some problems are the result of user error in
some way.) 

In order to help developers help you, the best thing to do is to
minimize the error to the *smallest amount of code that can cause it to
happen*. Additionally, when attempting to reproduce, any developer will
need to set up the code so that it is possible to run in the developer's
test environment. This means that it is ideal to remove external
references to other Javascript files, and external files at all, where
possible. (Clearly, this is not always possible: WFS server bugs can't
typically be demonstrated inside of a single page, for example -- but
you should minimize external dependancies as much as possible.)

Once you've done this, you should remove *all non-neccesary lines of
code* from your example. Does the problem require the ScaleBar control
in order to manifest itself? If not, toss it. Does it need multiple
layers? If not, toss them. In short, any line of code that is not
directly related to reproducing the problem should be removed, as each
line will need to be read by the developer -- and in the case of
multiple developers working on a problem, read by *each* developer -- in
order to determine whether the problem is related to that.

This minimization step should include removing any unneccesary
Javascript, unneccesary CSS files, unneccesary HTML, etc. until the
resulting code is as small as possible.

Many times, in doing this, you will come across a particular
minimization step that causes the problem to go away. This is a good
sign, because it means you have narrowed the problem down to that
particular aspect of code. Put it back, and keep minimizing.

Additionally, many times in doing this, you find a particular construct
in your code that can help you understand how to work around the
problem. 

If not, then continue onto the next section.

OpenLayers Library References
=============================

There are multiple hosted versions of the OpenLayers library. 

  http://openlayers.org/api/OpenLayers.js

This will always represent the most recent released 'stable' version of
the OpenLayers API.

 http://openlayers.org/dev/OpenLayers.js

This is always a 10-minute delayed build of OpenLayers trunk.

To simplify allowing developers to set up the code on their own testing
environments, it is often beneficial to point directly to one of these
library URLs. In addition, this also ensures that the problem is not
something specific to your build of OpenLayers. 

Publishing your Problem
-----------------------

Once you have minimized your test case, you need to publish it. In
general, it is easiest if you publish an HTML page on a web accessible
URL. Even if your project is not yet public, you can likely put a page
up on another server which demonstrates the problem. Doing this is much
more likely to have a developer actually follow the link and explore
your problem. This is *especially* true for things like WFS which
require a proxy to work correctly:  Downloading the page, setting up a
proxy, and testing locally is a lot of work for a developer simply to
confirm that a problem exists.

If you do not have *any* place to publish webpages, you can attempt to
paste your code to a public site like 'nopaste.com'. However, be aware
that doing so means that a developer has to perform more steps to
reproduce your problem -- and every step is one that makes the problem
less likely to be solved quickly and easily.

Communicating about your Problem
--------------------------------

The best way to communicate your problem is to send an email to the
users list demonstrating the problem. Oftentimes other users will be
able to point out a particular flaw in your code that is causing the
error, or explain that the behavior is a known lack of functionality in
OpenLayers.

*Be clear on steps for reproduction*. Users who don't know what they're
supposed to do to cause the bug will not be able to see it, and if they
can't see it, they can't help you.

If you have determined the particular change in the OpenLayers source
code which is required to change the behavior, then it is more likely
that the Developers list is the best place to go. Any discussion which
involves code from OpenLayers itself is probably better suited for the
dev list. 

Finally,
--------

By following the steps: 
 * Simplify/Minimize
 * Publish
 * Communicate

(If you'd like, you can toss a "???, Profit!" at the end of this.)

You can ensure that it is as easy as possible for a developer to
determine whether the problem you're having is with the library. You
also make it easier for develpoers and users to find potential problems
in your usage of the library and suggest solutions. Finally, you may
find in the process that you find the bug yourself, thus saving yourself
and everyone else time in trying to debug.

The end result is a more workable system for everyone. The easier it is
to understand the problem you're having, the faster, and more easily,
you will be able to get help.

Best Regards,
-- 
Christopher Schmidt
MetaCarta