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

Mon May 18 22:23:30 EDT 2009

On Tue, May 19, 2009 at 12:02:09AM +0200, Eric Lemoine wrote:
> thanks a lot for putting this email together Chris, shall we
> copy&paste it somewhere for future reference?

Yeah: I'm not sure if it amkes more sense as a wikipage, or someplace in
the docs. I figured I'd write it, and let someone else do that part if
they cared :)

-- Chris

> --
> Eric
> 
> On Friday, May 15, 2009, Christopher Schmidt <crschmidt at metacarta.com> wrote:
> > 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
> > _______________________________________________
> > Dev mailing list
> > Dev at openlayers.org
> > http://openlayers.org/mailman/listinfo/dev
> >
> 
> -- 
> Eric Lemoine
> 
> Camptocamp France SAS
> Savoie Technolac, BP 352
> 73377 Le Bourget du Lac, Cedex
> 
> Tel : 00 33 4 79 44 44 96
> Mail : eric.lemoine at camptocamp.com
> http://www.camptocamp.com
> _______________________________________________
> Users mailing list
> Users at openlayers.org
> http://openlayers.org/mailman/listinfo/users

-- 
Christopher Schmidt
MetaCarta