Proposed Specification for a Sandbox and Batch Edit Facility   


by

JD Scott, Unemployed
Greg Noel, Retired UNIX Guru
Blake Stephens, Programmer


In Short

Many people have expressed a desire either to have a way to try out edits to see what effect they have or to package a number of individual edits into a group and submit them for a single review.  Not only would such a facility allow newbies to try out dangerous operations in comparative safety, but also it would make reviewers more productive by requiring only a single review that covers any number of edits.

Introduction

Google Map Maker urgently needs a facility for sandboxes (where novice users can try out things to see how they work) and batch edits (where a set of related edits can be processed all together).  The need for this facility frequently shows up in the fora, but they are scattered over so many threads that it's impossible to see any consensus among them (the only consensus is that such a feature is badly needed).

The intent of this document is to create a consensus on the feature set required.  Most descriptions are vague on details; issues such as locking between different batch sets and controlling the scope of projects are not considered.  This proposal uses existing mechanisms to contain the scope of the changes, and so should provide an intuitive user interface as well as making it easier to understand the set of changes.

Issue 2070 in the issue tracker is the request to implement this feature.  This issue subsumes at least two other related issues (issue 85 for sandboxes and issue 263 for batch edits); they should be closed in favor of this issue.

Credit where credit is due: In the thread “Where MapMaker utterly fails” in the General Map Maker forum, JDScott suggested a set of concepts that should be included.  Greg Noel edited that into an implementation scenario.  The scenario was then critiqued by Blake Stevens, who caused a lot of loose ends to be tied up.  The resultant scenario is the basis for this document.

Proposal

This proposal is in a series of steps that the “typical” project goes through.  Please note that although the general flow is sequential, there are quite a few eddies and branches, so the flow for any given project can be quite diverse.

Step 1

Use a polygon (shape tool) to define a temporary 'Project Zone'.  In addition to the standard things for a polygon, the project zone attributes include:
  • The project name (optional, based on project scope?)
  • A concise statement of the project’s scope
  • The types of features that will be edited (see optimization below)
  • Collaborators (nominate some or accept volunteers)
  • A Google-assigned moderator (optional, see below)
  • A link to a project 'whiteboard' (see below)
  • A time limit by which the project must be completed
  • The number of 'eyes-on locals' and 'community members' needed for approval
  • Other stuff to be figured out

Some of these fields probably need to be modifiable while the details of the project are under discussion.

Blake Stephens suggests that the polygon should be yellowish-orange (#D8A200); he mocked up an example that shows the color in stripes.  Greg Noel proposes limiting the stripes to the boundary to make it look like the warnings that are used around construction sites (i.e., a black boundary with a fairly narrow band of warning stripes); this would allow editing without the distraction of an overlay color.  A more outrageous suggestion is to mark the boundary with orange traffic cones (to make the region a "cone zone" as they're called in SoCal).

It should be possible to tweak the polygon while the project scope is being settled.  Since it would be possible to undo the project and reopen a new one, this feature could be delayed until after the initial release of the functionality.

It probably should be possible to tweak the polygon after the project has started (after achieving consensus to do so).  The moderator would review and accept the new boundary before it was activated.

Step 2

If a line on the zone polygon crosses a routeable segment (i.e., road, path, trail, river, whatever) and one of the line's endpoints is near an intersection of the segment, that point snaps to the intersection.

If a line on the zone polygon crosses a routeable segment and neither of the line's endpoints is near an intersection of the segment, a temporary intersection is created at the point where they cross.  This temporary intersection is deleted when the project zone is discarded.

(Suggested implementation detail: Snapping the endpoints to an intersection probably should be done when the zone is created, while the temporary intersections should be created when the project is enabled.)

(Note: If implementing temporary intersections is too difficult to do quickly, it’s important to get the initial functional release out expeditiously.  A fallback implementation is to break the line (create a new point) and adjust the boundary to cross at an intersection (snap the new point to the nearest intersection of the segment).  This is more awkward for the user (as well as violating the principle of least surprise), so correcting this should be a high-priority enhancement.)

An optimization would be for a project zone to reserve only a subset of  the editable types (e.g., only water features [rivers and lakes] or only land routes [roads and trails] or only buildings).  Project boundaries that cross segments that are not in its reserved set would not need to create an intersection.

Step 3

After all the details are settled, the moderator enables the zone.
  • There can be no active project zone that conflicts with the new zone (i.e., reserving the same editable type in an overlapping area).
  • There can be no pending updates of a reserved editable type in the zone when it is enabled.
  • Intersections at the zone edges are locked.
  • Edits in the zone, except by collaborators, are precluded.
  • Precluded edit attempts should be directed to the project information (see the mock-up; people who attempted these edits may want to join the project).
  • Edits in the zone happen on an overlay layer.
  • Edits in the zone are instantly live (no approval required).

Note that locking the boundary intersections means that the geometry of the connecting segments, both outside and inside the zone, cannot be modified.  (Think of it as a safety buffer between the inside and the outside.)  The boundary will have to be selected with this in mind.

The idea behind a project is that work doesn’t start until there’s agreement on what is to be done.  On the other hand, some projects are small enough that it’s easier to show the results than it is to explain them.  Therefore, the system should not prevent work from starting before the project is officially approved; such work will usually get done sooner and require only one interaction with a moderator.  (Such a project should be called a ‘Sooner’ in honor of the Oklahoma settlers.)

If there is only one collaborator (and no moderator), that individual can enable the project as a 'sandbox'.  A sandbox will expire and be removed by the system if it is unused for a short time.  (Greg Noel: I can argue a time limit as short as three days or as long as seven, but I don't think it would be reasonable to have a time limit outside that range.)

In issue 85, alan.mi...@gmail.com (actual name unknown) suggests that sandboxes should be mapped into the Pacific ocean, far from land.  If individual project zones are used for sandboxes (see the first use case below), this would make the sandbox 'island' look and feel just like any other map location, and would be useful for things like discussing problems in the fora, since links to the location would not require fiddling with overlays or anything like that.

Step 4

Some sort of 'whiteboard' would have to be available for communication between collaborators and for comments from those not in the group.  The whiteboard link would be part of the project attributes.

Initially, this whiteboard could be as simple as a thread in a forum (possibly a forum dedicated to projects).  People interested in the project would monitor the thread.  (I believe it's possible to mail thread updates to the user starting the thread; it may be possible that users could sign up for thread updates as well.)

There are probably a number of other tools, like a wiki page or a blog, that could be used to communicate.  And it's not even required that Google provide the service; the collaborators can select a tool based on their specific needs.

In the long run, larger projects might like to have a true project-based whiteboard, with sub-projects that can be delegated to the people working on them, and a dependency graph to show how the pieces fit together.  But this sort of thing is a frill, and there are sites that offer free project management functionality for open-source projects.  Maybe all that has to happen is for Google to negotiate access to such a site (or maybe more than one?).

Step 5

It should be possible to add new collaborators to the group as well as drop dormant collaborators.  I would expect that these actions would be within the purview of the moderator, who would be expected to adapt to the sense of the group in executing these actions: some projects would want to take a formal vote, other projects might expect consensus, while other groups would be more laissez-faire.

Step 6

Internal approval prior to release requires that all of the "whiteboard group" members sign off that each segment, POI, building, etc. is 'accurate' and 'complete'.

There should be guidelines to help achieve this consensus.  If someone feels ambitious, they can create a section below to outline what such guidelines should contain.

Step 7

For final approval, the project must accumulate some predetermined number of approvals from the community of mappers at large; some specified subset must be 'eyes-on locals'.  The numbers would be set during project setup based on established guidelines (although one hopes that the guidelines state that the exact number of approvals is not fixed, but is based on the individual project and its location, as a small project in Manhattan might have a dozen eyes-on locals, while a similar project in Podunk might only have one).

(Guideline note: A likely way to accumulate these approvals is to recruit the needed users in advance and bring them on board as observers.  When the project competes, the votes can be accumulated immediately.)

Step 8

Moderator pushes the "go live" button; all of the "old" disappears (as does the project polygon and its locks) and the "new" takes its place.

Everybody goes out and has a beer.

Enhancements

After the initial release of functionality, I would expect that the development team will tackle a series of enhancements.  Some of them are noted above in the scenario, but there are some others as well.  These are in no particular order.

1. It should be possible to release an intermediate state.  This would need some procedures to validate that existing routes haven’t been altered and probably some review process.

2. If not implemented in the initial release, it should be possible to restrict the types of edits that can be performed in a zone.  It should be possible to establish overlapping zones if they do different types of edits.  (For example, a project to outline all the businesses in a neighborhood could overlap with a project to map a parking lot in the same neighborhood.)

3. (Controversial) Instead of freezing all edits by outsiders, evaluate the features lazily and only freeze external edits for features that are actually touched by the project.  If an (approved) edit is touched by the project, it picks up the latest and greatest update; if the edit is pending, the project members (via the moderator?) have the power to either approve or disapprove the edit.

Moderator

The moderator is the person who represents to Google that the map modifications are beneficial.  There should be guidelines established to codify this task.  This section outlines a few points that should be in those guidelines.

In general, the moderator signs on for the duration of the project.  Whether assigned by consensus or self-assigned, by being assigned to a project, the moderator agrees to track the project regularly and keep abreast of any problems.  It's also the moderator's responsibility to respond quickly to project requests.

This rule is not hard and fast, but the moderator is not usually a collaborator in the project, so that he or she can remain independent of any partisan conflicts that may occur.

It is the responsibility of the project members to keep themselves on track.  In the event that they lose traction, it's the moderator's job to step in and determine what should be done.

The project has a deadline.  If the project goes past its deadline, the moderator should consider terminating the project.

In the case that a moderator goes dormant or rogue, the tactic should be to bring it up on the General Map Maker forum for wider discussion and resolution.

A cynical critique of these points will observe that these guidelines mean that the moderator’s job must be to encourage project members to make high-quality edits since they normally won’t be able to rack up edits on their own behalf.  A cynical critique would have a point.

Use Cases

These use cases are not highly original and do not stretch the possible range of options very far.  Contributions of additional use cases would be welcome.

1. An individual could create a project region without a moderator.  This would be a 'sandbox' and restrictions would apply: the region would not be visible except to the creator, it would not block other edits in the region, the region could never go live, and it would automatically be deleted after some period of inactivity.

2. For small projects like a parking lot or a cloverleaf intersection, an individual could create a project and advertise for a moderator.  Basically the same process would be used as for locating a trusted reviewer to approve an edit.  Other users could chime in with recommendations (pro or con) and eventually a moderator will either volunteer or reject the proposal.

The advantage to this scenario is that while there could be some frustration until a moderator turns up, once there is one, not only would there be minimal frustration during the actual editing, but also the moderator would be committed to respond quickly once the editing was completed, so the time waiting for action should be much shorter and much less frustrating.

3. A couple of locals could collaborate on a mall or shopping center.  One could place the roads and the other draw the buildings.

4. Bigger groups of collaborators could be assembled for larger projects or larger regions.  Ideally, the collaborators should have a mix including eyes-on locals, expert (trusted) editors, and a Google-assigned moderator.  (The categories are not exclusive.)  Sorry, no newbies.

Additional notes

Various comments on things related to this proposal.

History

Reviewing a project can be a big task.  It’s beyond the scope of this proposal, but there will have to be a better way of looking at the combined history of a set of features in a project or reviewers will simply be unable to do it.  Making the history easier to understand for a project will also make it easier to understand the history of an individual feature.

Counting coup

If users continue to be rated on the simple metric of edits approved and edits denied, projects will throw a distinct curve in the statistics.  How are edits counted when the project is completed?  Just counting the edits in the project is too easily gamed (create a project, do one thousand edits just flipping one value back and forth, then complete the project).  Instead, no matter how many changes a collaborator made to a given feature, they should be counted as a single edit.  (A competent editor shouldn’t make more than a couple of changes to a given feature, so this is not too far out.  Even if you go back in and tweak something several times, it’s all part of the same process.)  Creating a feature and then later deleting it (or a sequence of edits that has no net effect) counts as zero edits.  Moreover, if one believes that most edits will eventually be done in projects (most updates require editing more than one feature; even mapping a parking lot involves creating multiple road segments), then singleton edits will be more isolated and won’t require the delegation of so much power to so many people.

Delegating power

Speaking of delegating power, one thing that isn’t highlighted enough in this proposal is that it can work well with far less delegation.  Instead of approval being needed at every step, a dozen (or a hundred or a thousand) steps can be wrapped in a single bundle and approved all at once.  Instead of users being delegated the ability to lay roads unsupervised, they can establish a project to add a parking lot, lay a dozen roads, tweak them, get the geometry and attributes correct, and then submit all of it for review.  No authority is delegated; there’s still a review step where a more-experienced mapper can verify that it was done correctly.  (This is a good thing; I think I’m competent to lay roads, but I’d actually prefer that a second set of eyes made sure I hadn’t missed anything.)

Maybe the new power hierarchy is based on how many edits a reviewer can approve in a single project.  That is, for a project with seventeen edits in it, it takes two ten-edit reviewers or one twenty-edit reviewer.  (Yes, this is somewhat at cross-purposes with the model presented above, but the idea of this document is to generate discussion about the best way to do it, including the approval process.  Maybe the moderator has to have a large enough approval rating to handle the estimated size of the project.)
Comments