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

Tue May 19 12:09:27 EDT 2009

Dear Chris,

Many thanks for this email- it's possibly one of the most useful things I've
read in weeks! Personally I'd like to apologise for not always following
these instructions, but (and I think I speak for a lot of n00bs and relative
n00bs to openlayers), learning how to ask for help correctly has  been as
much of a challenge as learning how to use the code. I'd love to see this
somewhere in the documentation, and would be happy to help get it there if
you decide where you'd like to see it!

Jo

Christopher Schmidt-2 wrote:
> 
> 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
> _______________________________________________
> Users mailing list
> Users at openlayers.org
> http://openlayers.org/mailman/listinfo/users
> 
> 

-- 
View this message in context: http://n2.nabble.com/Getting-Help-Faster%3A-Minimize-Your-Code-tp2908661p2940529.html
Sent from the OpenLayers Users mailing list archive at Nabble.com.