Not my own words, but copied verbatim from Chris Schmidt on the OpenLayers Mailing List. Change the name, and they are mostly applicable to any package, not just OpenLayers. Having been guilty of not following these instructions myself, I’d advocate that all new mailing list subscribers should read it before signing up…

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

Well, since my last post, I discovered that my site had been hacked andwas trying to install a trojan on people’s machines (thanks for letting me know, Bill). I got my account suspended by my web hosts as a result, and got into a bit of a spat with them about how they handled it (absolutely nothing on their support site about it, but apparently you’re supposed to tell them IMMEDIATELY when things like that happen). So, apologies if anyone got infected by visiting archaeogeek.com, I do apologise. I know archaeologists are dirty sorts (it’s all that playing around in the mud), but we’re not supposed to be contagious!

I have also had a great week exploring mapfish and openlayers, as I discussed a couple of weeks ago. It’s been great fun (in an intellectually challenging sort of way) because I have come from a position of almost total ignorance of things like javascript, to being reasonably happy with the map that I’ve produced, and more importantly, I feel as if I understand what I’ve done. This is a break from tradition for me- my normal approach is to take code that I don’t fully understand and hack it till it works. Not this time though! It’s on an internal dev-server at the moment, but as soon as I get an external URL I’ll post it for comment.

I’ve also been exploring google chrome a lot more. When it first came out, I was quite disappointed in it. However, when doing web development and using all those essential firefox extensions, like firebug, httpfox, and webdeveloper, the browser can get a little bloated. So I’m using chrome as my standard browser and firefox for development work. I’ve decided that it’s not that bad- though somehow the time it takes to initially load a page (when it goes through resolving the host and all that) still seems longer than I would expect and I do grow impatient with it. I had also trained myself to use ubiquity, and to “ctrl-space” anything that I wanted to look up, but of course that doesn’t work at all…

I started off this week with the intention of resurrecting and upgrading a demo openlayers map of all our sites, that had been stuck in a sorry corner of our corporate website being neglected. This tied in with moving the map to a different server, upgrading all the components, and generally giving it a shave and a haircut (it is male, that’s for certain). For those people interested in our wms and wfs data- these will be online again soon, I promise.

While I now have a site up again, pretty much ready to go bar the shouting, I’ve had an interesting time playing with some new toys in the process, so here’s a quick run-down:

• Mapfish and GeoadminSuite: A funky framework for widgetising openlayers. Geoadminsuite connects mapserver, openlayers and mapfish to manage data and create really nice mapfish applications. Way cool. Progress so far- it’s all up and running, though GeoadminSuite had teething troubles that have hopefully been sorted in the latest svn release.
• Openlayers: OK, so I’m just catching up with the latest release after ducking out for a while to do “real work”, but I have to say I like the new(er) features. It was nice to be able to do popups without needing to re-write the code for every version of every flavour of browser. That’s not openlayers’ fault of course, just issues with “standards” for things like DOM, which I don’t claim to understand.
• Openstreetmap WMS data from Wheregroup: Comes in free and paid-for flavours though details on pricing and terms of service for the commercial version were sketchy on a first skim of the website. This could be really handy to use as background mapping data for web maps, although there are issues of completeness (as always) and it probably needs running through our own mapserver to sort out the styling. This is definitely a goer- I just need to figure out which of the 50 or so layers they publish are really necessary and at what scale. And some kind of completeness metric, so we know how reliable the data is for a given area…
• Openstreetmap shapefiles from Cloudmade: A reduced dataset for the UK, with less layers. This might be a better option for us to use as we can control the styling better at the source. As a cheat, I’m going to load it all up in Quantum GIS, style it there, and use the mapserver export plugin to quickly build my map file.
• Mapnik: One of my colleagues would very much like us to create our own openstreetmap wms server, and use mapnik. I’d love to, as the cartography is really good, but after diving into it today, I have to say I think I need some hand holding before I can actually make it serve maps. We’ll see…

Also rans:

• Ordnance Survey have changed the licensing for their OpenSpace product: You still need a license to use their data, but you can download the development kit from sourceforge. The license has also been changed to have more “clarity” in terms of the ownership of derived data. It would be churlish to suggest that this has anything to do with the “Show Us a Better Way” mess up, wouldn’t it? The problem is, you still need to pay for the background data, so we’re back up to points 2 and 3 above…
• Amazon launches public datasets: This, in my limited experience, seems to be a duplication of ideas that are already out there. That’s fine when it’s software, and you want to stomp all over your rivals, but wouldn’t it have been nice for them to give their support to an existing data repository?

Things to play with next:

• Openaerialmap: Also has a wms service…

The title says it all really, Archaeogeek’s second birthday snuck by the other day without me even noticing. Mr Archaeogeek says this means I have to take him out for dinner. I’m sure he has it the wrong way around, but maybe he needs rewarding for putting up with me! Anyhow, happy birthday to Archaeogeek. I’m even more astounded than I was this time last year that my attention span has lasted this long, given that it has actually been a pretty tough year around these parts. Ah well, here’s to the next year- let’s hope this toddler doesn’t have too much of the “terrible-twos”!

In other news, there was a pretty low-key announcement from the British Cartographic Society about their 2008 Awards for “Excellence in [cartography]“. Props to the Openstreetmap/OpenLayers powered OpenCycleMap, and the Thames Estuary Coastal Habitat Atlas (can’t find a link to this) for triumphing in the Electronic Mapping category. However, tucked away at the bottom of the article was the following telling statement (slightly paraphrased): “(The Ordnance Survey Mastermap Award for Better Mapping was not awarded because there) was minimal or no innovative use of OS MasterMap data”. So… that’s what happens when you make the data too expensive to use… you get no innovative uses of it!

And finally, if you were worried about the affects of the switch-on in Cern earlier this week, well don’t worry. This website will help, and there’s even an rss feed for it. Phew!

This is an idea that seems to come up every so often- what GIS programmes can you run from a USB stick. Well it appears that the list has just got longer. I’m probably the last person to realise it’s possible to do this, but I was really pleased to see that both GRASS and PostgreSQL can now be run from a USB stick, along with QGIS, XAMPP (inc Mapserver, OpenLayers, Tilecache), and FWTools.

Before I go any further, I should state that my aims for creating a portable GIS are not so much having a production GIS setup on a stick, because obviously performance and storage are an issue, but it might be useful for demonstration purposes, and I do feel as if the take up of these opensource tools might be more if they were easier to install and came in one handy package. So what I really want to achieve is a single portable package, probably a zip-file, that can be downloaded and unzipped onto a Window pc (they can learn about the joys of linux once we’ve won them over to the basic concept of opensource). No separate downloads, long installation and configuration processes, just a zip file. I do also like having portable packages on my main computer, as if it breaks it’s a lot easier to reconstruct the setup!

The light-bulb moment for me was when Leif told me that he had seen GRASS working on a USB stick using Msys at the recent CAA conference in Berlin. This intrigued me, so I looked into it and it works quite nicely- as long as you use the same drive letter to mount your USB stick to all the time. I still have to figure out how to figure out the drive letter and change the paths, probably in a batch file. Put simply, you download Mingw and Msys onto the stick, follow the instructions for downloading GRASS, edit the install_grass.bat file to change the drive letters, and off it goes.

PostgreSQL was something I had looked into a while ago, been told it wasn’t possible, and given up on. However, the recent 8.2 release appears to have dropped the requirement for a dedicated non-administrative user to run it. If you download the windows binaries, without the installer, you can set it up whilst logged on as the standard user. When you next run PostgreSQL from a different machine, you just have to use the same username as on your installation pc, regardless of whether that user exists on the pc that you are currently using. Once you have PostgreSQL installed, you can install Postgis into the same directory.

Currently there are a couple of gotchas. Most of these programmes require you to set environment variables, which might not be allowed on the particular pc that you are using, and require some command line experience. I still haven’t quite figured out how to get GRASS to work if I change the drive letter. Also, PostgreSQL does indeed run very slowly on a USB stick. And, I haven’t fully explored this to make sure there isn’t a hidden trap somewhere, or security holes that might be exploited. Having said that, if you want a package that can be unzipped onto a pc with a minimum of fuss then I think it’s almost there.

What’s next? Documentation, as always, and the permission of the various programmers that it’s OK to do this. Oh, and comments please, on what else we might include, or words of wisdom if you’ve already tried it.

Archaeogeek is now back in the saddle/desk-chair after a few weeks break- firstly entertaining visiting parents and most recently scuba-diving in the Sound of Mull (Scotland)

In the mean time I have a few projects coming to fruition, and have been catching up on a few things that I wanted to learn more about (hello google maps and database integration). Firstly, we at Oxford Archaeology have been fortunate to have the services of a very skilled and enthusiastic work-placement student called Matt Jones from the University of Southampton for the last few weeks and he has been helping up get our basic web-based mapping sorted. This collaboration was the first to be arranged via the Antiquist Skills Exchange, where people can post about work they have available, or skills they can offer. It’s still a work in progress to some extent but Matt has done sterling work getting it looking good. Thanks also to Bill Woodall from the OpenLayers mailing list who helped immensely with the ajax code for getting the popups to work nicely.

Secondly, I have been fortunate to have some communication with the MapGuide Open Source development team in terms of getting MGOS working on Ubuntu. This is a long process, made slightly more difficult because of the difference in time zones, but we are making progress, and I am just amazed at them for assigning someone to spend time working with me to get the programme working. I can’t honestly imagine many large companies doing this, and it’s a great credit to the new open mindset at Autodesk. We are currently working through the compilation errors as they occur in the code, and I am taking copious notes so I’ll keep people posted.

Thirdly, Oxford Archaeology’s decision to release our data via wms/wfs is still a matter of debate. Unfortunately for every post or comment that approves of our decision, there is another that tries to figure out what we are gaining financially from the decision. I find this sad, as it’s indicative of a mindset in British Archaeology that we are trying to change. I’m not being naive- we might make some fuzzy and indirect gains from this, and certainly our internal efficiency will improve, but it’s really not the main point- we are making a commitment to the free exchange of data.