New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal for design goals and guidelines - part 1 #2446

Merged
merged 3 commits into from Nov 23, 2016

Conversation

Projects
None yet
6 participants
@imagico
Collaborator

imagico commented Nov 17, 2016

I have started with a draft of putting together some design principles for this style that hopefully help contributors in the future to better understand the direction of development.

This first part contains two of three sections i structured this into. These two are the description of the style purposes and a list of the main goals derived from these. I plan to supplement this with a section with more specific guidelines on style decisions with - from my side - subsections on colors and zoom levels - which can be supplemented by others on further subjects like for example icon design.

This structure is meant to show that the specific principles listed are not arbitrary but are meant to serve the described goals which are followed to make the style serve its purposes.

Mostly i tried to put together ideas that i hope we can mostly agree upon. But there are also a few things that might be more controversial. The most significant probably is that i put the goals into an order which - as i put it at the moment, is quite a bit different from the current priorities. In my eyes point 5 and 6 currently have a much higher priority while point 3 is often less important.

To give an example (just an example, not meant to reopen the discussion) the decision to close #1853 was based on the maintainability aspect although in my eyes the change was a significant improvement regarding at least goal 2 and 3.

I am open to changing this order based on arguments discussed here, alternatively we can also make this an unordered list but an order of the goals would of course make priorities clearer for potential contributors.

The ordering as i put it for the moment represents the priorities the different goals would have for me - but of course we should ultimately put them in the order that represents actual practice.

Show outdated Hide outdated CARTOGRAPHY.md Outdated
@matthijsmelissen

This comment has been minimized.

Show comment
Hide comment
@matthijsmelissen

matthijsmelissen Nov 17, 2016

Collaborator

Looking good!

I think you're interpreting legibility too narrow. For example, the old Luxembourg bus map is perfectly intuitively understandable, but very hard too read. In comparison, the new Luxembourg bus map is much easier to read.

Perhaps under Diversity, or as a separate point, you could also add that the map does not cater to one specific type of user (car drivers, cyclists etc.) but tries to be useful for all?

Collaborator

matthijsmelissen commented Nov 17, 2016

Looking good!

I think you're interpreting legibility too narrow. For example, the old Luxembourg bus map is perfectly intuitively understandable, but very hard too read. In comparison, the new Luxembourg bus map is much easier to read.

Perhaps under Diversity, or as a separate point, you could also add that the map does not cater to one specific type of user (car drivers, cyclists etc.) but tries to be useful for all?

@imagico

This comment has been minimized.

Show comment
Hide comment
@imagico

imagico Nov 17, 2016

Collaborator

I think you're interpreting legibility too narrow.

My idea was that the top goal that stands above all others is the basic legibility. Ease of use is more what i had in mind with the Clarity goal. But if preferred we can combine them and put them on top as general legibility including ease of use. Currently however my impression is that being easy to read often does not have priority over mapper feedback - we would do more geometry processing then for example.

Perhaps under Diversity, or as a separate point, you could also add that the map does not cater to one specific type of user (car drivers, cyclists etc.) but tries to be useful for all?

Maybe just add or to special thematic interests of users at the end of the diversity goal? Alternatively feel free to add it as you see fit, the idea in general is very good.

Collaborator

imagico commented Nov 17, 2016

I think you're interpreting legibility too narrow.

My idea was that the top goal that stands above all others is the basic legibility. Ease of use is more what i had in mind with the Clarity goal. But if preferred we can combine them and put them on top as general legibility including ease of use. Currently however my impression is that being easy to read often does not have priority over mapper feedback - we would do more geometry processing then for example.

Perhaps under Diversity, or as a separate point, you could also add that the map does not cater to one specific type of user (car drivers, cyclists etc.) but tries to be useful for all?

Maybe just add or to special thematic interests of users at the end of the diversity goal? Alternatively feel free to add it as you see fit, the idea in general is very good.

@matthijsmelissen

This comment has been minimized.

Show comment
Hide comment
@matthijsmelissen

matthijsmelissen Nov 17, 2016

Collaborator

To be honest I'm a bit skeptic about us being able to order the goals in terms of priority. Otherwise we'd end up having to block big progress in one area because it would mean a small regression in another area. I'd be more comfortable with an unranked list.

Collaborator

matthijsmelissen commented Nov 17, 2016

To be honest I'm a bit skeptic about us being able to order the goals in terms of priority. Otherwise we'd end up having to block big progress in one area because it would mean a small regression in another area. I'd be more comfortable with an unranked list.

Show outdated Hide outdated CARTOGRAPHY.md Outdated
@nebulon42

This comment has been minimized.

Show comment
Hide comment
@nebulon42

nebulon42 Nov 17, 2016

Contributor

Very good work and very good starting point. Yes, a ranking is maybe a bit hard to obey. But on the other hand things like feedback-loop/feature-richness and clarity/aesthetics always get us into trouble. A ranking would help to indicate a general direction. This could be also indicated at the end of a unordered list. A long term goal should be to reduce the central importance of openstreetmap-carto for OSM by having more different main styles. But this might require basic changes to the rendering infrastructure and is of course out of scope here.

Contributor

nebulon42 commented Nov 17, 2016

Very good work and very good starting point. Yes, a ranking is maybe a bit hard to obey. But on the other hand things like feedback-loop/feature-richness and clarity/aesthetics always get us into trouble. A ranking would help to indicate a general direction. This could be also indicated at the end of a unordered list. A long term goal should be to reduce the central importance of openstreetmap-carto for OSM by having more different main styles. But this might require basic changes to the rendering infrastructure and is of course out of scope here.

@imagico

This comment has been minimized.

Show comment
Hide comment
@imagico

imagico Nov 17, 2016

Collaborator

Keep in mind the purpose of this is not to set constraints for us to obey - we set the goals, we can also change them. The main purpose is to help contributors understand what the basis is of the design decisions we make. So if the goals have an order of priorities for us we should document that, even if practically this ordering is very weak.

Maybe we could just collect a set of opinions from the maintainers if and how the different goals have priorities for them - like 'all the same importance to me', '2 is most important but the rest is all the same to me', '1,4 and 7 are slightly more important than 2,3,5 and 6' or a fully sorted list. But before we do that we might better think about if we missed any important goals.

Collaborator

imagico commented Nov 17, 2016

Keep in mind the purpose of this is not to set constraints for us to obey - we set the goals, we can also change them. The main purpose is to help contributors understand what the basis is of the design decisions we make. So if the goals have an order of priorities for us we should document that, even if practically this ordering is very weak.

Maybe we could just collect a set of opinions from the maintainers if and how the different goals have priorities for them - like 'all the same importance to me', '2 is most important but the rest is all the same to me', '1,4 and 7 are slightly more important than 2,3,5 and 6' or a fully sorted list. But before we do that we might better think about if we missed any important goals.

@kocio-pl

This comment has been minimized.

Show comment
Hide comment
@kocio-pl

kocio-pl Nov 18, 2016

Collaborator

A bit off topic, because we lack place to discuss general things (do we want to have one?): I've just found a journey planner which uses osm-carto with different colors, that's an example of 7. (adaptability).

Collaborator

kocio-pl commented Nov 18, 2016

A bit off topic, because we lack place to discuss general things (do we want to have one?): I've just found a journey planner which uses osm-carto with different colors, that's an example of 7. (adaptability).

@matthijsmelissen

This comment has been minimized.

Show comment
Hide comment
@matthijsmelissen

matthijsmelissen Nov 18, 2016

Collaborator

I think the performance of the rendering is also one of the design goals. Making style changes gets harder and harder the longer stylesheet parsing takes.

Collaborator

matthijsmelissen commented Nov 18, 2016

I think the performance of the rendering is also one of the design goals. Making style changes gets harder and harder the longer stylesheet parsing takes.

@matthijsmelissen

This comment has been minimized.

Show comment
Hide comment
@matthijsmelissen

matthijsmelissen Nov 19, 2016

Collaborator

I've just found a journey planner which uses osm-carto with different colors, that's an example of 7. (adaptability).

I think this journey planner (or at least the polish version e-podróżnik) is around longer than osm-carto, so it's more likely based on the style preceding osm-carto.

Collaborator

matthijsmelissen commented Nov 19, 2016

I've just found a journey planner which uses osm-carto with different colors, that's an example of 7. (adaptability).

I think this journey planner (or at least the polish version e-podróżnik) is around longer than osm-carto, so it's more likely based on the style preceding osm-carto.

@kocio-pl

This comment has been minimized.

Show comment
Hide comment
@kocio-pl

kocio-pl Nov 19, 2016

Collaborator

Looking at some osm-carto specific problems (#688) their style has been updated at some point.

Collaborator

kocio-pl commented Nov 19, 2016

Looking at some osm-carto specific problems (#688) their style has been updated at some point.

@imagico

This comment has been minimized.

Show comment
Hide comment
@imagico

imagico Nov 19, 2016

Collaborator

Regarding performance - this in my eyes has three components:

  • the constraint that we can't put too much additional load on the OSMF servers with style changes. I don't think this should be part of the design goals since this is an absolute external contraint like the database schema and (to some extent) the software used. It might make sense to list these in a separate document of course to help new contributors understand what they can and cannot do on a technical level.
  • the internal performance needs regarding our work - this should be part of maintainability i think.
  • the goal to keep the style not too demanding on tile serving infrastructure so others can use it fairly easily - this is kind of related to the adaptability goal.

Technically the first and last points are mostly about style rendering performance while the second is more about code complexity and parsing performance. We could acknowledge these goals with the following additions:

  1. Maintainability - The implementation of this style should not be too hard to maintain. This refers to both the volume and complexity of the code and how fast the style can be parsed when rendering it, which is very important for efficient development work. So the amount of code should be kept small and complex and fragile interdependencies should be avoided. If the code is difficult to maintain this would ultimately seriously affect all of the above goals.
  2. Adaptability and ease of use - The style should be easy to customize, like for creating localized or special purpose maps. It is also important to keep demands on rendering infrastructure for serving the style low so it is not too difficult and costly to set up a tile server for this style or a specialized variant of it.
Collaborator

imagico commented Nov 19, 2016

Regarding performance - this in my eyes has three components:

  • the constraint that we can't put too much additional load on the OSMF servers with style changes. I don't think this should be part of the design goals since this is an absolute external contraint like the database schema and (to some extent) the software used. It might make sense to list these in a separate document of course to help new contributors understand what they can and cannot do on a technical level.
  • the internal performance needs regarding our work - this should be part of maintainability i think.
  • the goal to keep the style not too demanding on tile serving infrastructure so others can use it fairly easily - this is kind of related to the adaptability goal.

Technically the first and last points are mostly about style rendering performance while the second is more about code complexity and parsing performance. We could acknowledge these goals with the following additions:

  1. Maintainability - The implementation of this style should not be too hard to maintain. This refers to both the volume and complexity of the code and how fast the style can be parsed when rendering it, which is very important for efficient development work. So the amount of code should be kept small and complex and fragile interdependencies should be avoided. If the code is difficult to maintain this would ultimately seriously affect all of the above goals.
  2. Adaptability and ease of use - The style should be easy to customize, like for creating localized or special purpose maps. It is also important to keep demands on rendering infrastructure for serving the style low so it is not too difficult and costly to set up a tile server for this style or a specialized variant of it.
@matthijsmelissen

This comment has been minimized.

Show comment
Hide comment
@matthijsmelissen

matthijsmelissen Nov 19, 2016

Collaborator

Sounds good to me.

Collaborator

matthijsmelissen commented Nov 19, 2016

Sounds good to me.

@pnorman

This comment has been minimized.

Show comment
Hide comment
@pnorman

pnorman Nov 20, 2016

Collaborator

Our meeting of the goals needs to balance them against each other. An unordered list might make this clearer.

Collaborator

pnorman commented Nov 20, 2016

Our meeting of the goals needs to balance them against each other. An unordered list might make this clearer.

@pnorman

This comment has been minimized.

Show comment
Hide comment
@pnorman

pnorman Nov 20, 2016

Collaborator

This might belong in a follow up discussion and PR, but these are thoughts I've been having on what we render. Features should be

  • useful to someone looking for something on a map remotely;
  • used to understand the general character of an area;
  • used for finding something when you're in the area;
  • used for orienting yourself when in an area; or
  • commonly rendered on many maps.

So a specialized shop not of general interest would not need its own icon, but somewhere to eat does.

Collaborator

pnorman commented Nov 20, 2016

This might belong in a follow up discussion and PR, but these are thoughts I've been having on what we render. Features should be

  • useful to someone looking for something on a map remotely;
  • used to understand the general character of an area;
  • used for finding something when you're in the area;
  • used for orienting yourself when in an area; or
  • commonly rendered on many maps.

So a specialized shop not of general interest would not need its own icon, but somewhere to eat does.

@Ircama

This comment has been minimized.

Show comment
Hide comment
@Ircama

Ircama Nov 20, 2016

Contributor

IMHO, the order proposed by @imagico looks appropriate and there are principles of a certain depth.

I would also suggest, when possible, that the standard style should tend to give more priority to features with wide social and cultural relevance and to basic topographic features (meaning the ones that are of common usage and that can be usually found on generic maps to physically describe the territory) rather than business elements (like shops, malls or factories).

Contributor

Ircama commented Nov 20, 2016

IMHO, the order proposed by @imagico looks appropriate and there are principles of a certain depth.

I would also suggest, when possible, that the standard style should tend to give more priority to features with wide social and cultural relevance and to basic topographic features (meaning the ones that are of common usage and that can be usually found on generic maps to physically describe the territory) rather than business elements (like shops, malls or factories).

@imagico

This comment has been minimized.

Show comment
Hide comment
@imagico

imagico Nov 20, 2016

Collaborator

I made a change with the following modifications:

  • since there has been no clear voice in support of an order of priorities for the goals from any other maintainer the goals are now in an unordered list.
  • since without an order of priorities it does not matter anyway i combined the clarity goal with legibility.
  • the last two goals are modified as indicated
  • i tried to integrate the suggestion from @nebulon42 into the mapper feedback purpose.

From my side this would be a reasonable first version but subsequent adjustments will of course likely be necessary. Also some proof reading regarding language and orthography would likely be good.

I still think it would be good to have an idea where the maintainers stand regarding the priorities of the different goals even if we don't want to define such an order for the project. But i don't want to push this. Please speak up if you think we should do this.

Regarding decisions on what to render and what not to render - i have a few considerations on this in my notes for more specific guidelines i will put in a supplement proposal. But in general this is fairly difficult, especially if it goes into subjective concepts like usefulness.

@Ircama - relevance is a problematic concept here - this is always highly subjective. I try to concentrate on things here that are at least to some extent objective so contributors can check their idea aginst these goals and guidelines without the inevitable frustration that would occur if you consider something highly relevant but find out that the maintainers do not.

There will of course always also be subjective decisions but we can at least try to document the basis for those which are not.

Collaborator

imagico commented Nov 20, 2016

I made a change with the following modifications:

  • since there has been no clear voice in support of an order of priorities for the goals from any other maintainer the goals are now in an unordered list.
  • since without an order of priorities it does not matter anyway i combined the clarity goal with legibility.
  • the last two goals are modified as indicated
  • i tried to integrate the suggestion from @nebulon42 into the mapper feedback purpose.

From my side this would be a reasonable first version but subsequent adjustments will of course likely be necessary. Also some proof reading regarding language and orthography would likely be good.

I still think it would be good to have an idea where the maintainers stand regarding the priorities of the different goals even if we don't want to define such an order for the project. But i don't want to push this. Please speak up if you think we should do this.

Regarding decisions on what to render and what not to render - i have a few considerations on this in my notes for more specific guidelines i will put in a supplement proposal. But in general this is fairly difficult, especially if it goes into subjective concepts like usefulness.

@Ircama - relevance is a problematic concept here - this is always highly subjective. I try to concentrate on things here that are at least to some extent objective so contributors can check their idea aginst these goals and guidelines without the inevitable frustration that would occur if you consider something highly relevant but find out that the maintainers do not.

There will of course always also be subjective decisions but we can at least try to document the basis for those which are not.

@imagico

This comment has been minimized.

Show comment
Hide comment
@imagico

imagico Nov 22, 2016

Collaborator

I have a first version of the second part ready now - i can add it here but it might be better to merge this first and start a new PR.

Collaborator

imagico commented Nov 22, 2016

I have a first version of the second part ready now - i can add it here but it might be better to merge this first and start a new PR.

@pnorman

This comment has been minimized.

Show comment
Hide comment
@pnorman

pnorman Nov 22, 2016

Collaborator

I have a first version of the second part ready now - i can add it here but it might be better to merge this first and start a new PR.

👍

If none of the other maintainers merge it, I'll have a last read through in the morning when I've had more sleep.

Collaborator

pnorman commented Nov 22, 2016

I have a first version of the second part ready now - i can add it here but it might be better to merge this first and start a new PR.

👍

If none of the other maintainers merge it, I'll have a last read through in the morning when I've had more sleep.

@nebulon42

I had some syntactical remarks (spaces), but Markdown won't render them anyway. Some remarks that can also be addressed after merging.

## Purposes
This is an attempt to outline the goals of this style and the principles under
which the maintainers make decisions. These rules are not set in stone, they

This comment has been minimized.

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra space between sentences.

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra space between sentences.

Show outdated Hide outdated CARTOGRAPHY.md Outdated
Firstly, this is a map, not merely a colourful 2-dimensional visualisation of the database. Colours should be chosen based on their effectiveness and to make things look nice, not chosen for distinctiveness.
There is no ranking of these purposes. To allow serving all of them and to

This comment has been minimized.

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra space between sentences

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra space between sentences

Colour definitions should, where useful, be put into variables at the top of the file, to enable easier customisation.
The following goals need to be balanced against each other to serve the purposes
above. There is no fixed order of priorities. Apart from these goals there are

This comment has been minimized.

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra spaces between sentences.

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra spaces between sentences.

* **Legibility and clarity** - The map should be intuitively readable by users with some general experience using maps without a map key, preferrably with relatively little effort. A map key or more extensive experience using this map style can be required for clearly identifying minor differences or the exact meaning of certain features but in broad strokes orientation and identification of map elements should be possible on an intuitive level. We also aim for the map appearance to be esthetically pleasing.

This comment has been minimized.

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra spaces between sentences.

@nebulon42

nebulon42 Nov 22, 2016

Contributor

Extra spaces between sentences.

Show outdated Hide outdated CARTOGRAPHY.md Outdated
Show outdated Hide outdated CARTOGRAPHY.md Outdated
Show outdated Hide outdated CARTOGRAPHY.md Outdated
Show outdated Hide outdated CARTOGRAPHY.md Outdated
@imagico

This comment has been minimized.

Show comment
Hide comment
@imagico

imagico Nov 23, 2016

Collaborator

Changed some formulations based on suggestions by @nebulon42. What i did not change is

  • sentence spacing - i am old fashioned, see https://en.wikipedia.org/wiki/Sentence_spacing.
  • on locally differentiated rendering - that would belong in the more specific guidelines to follow.
  • being easy for new contributors - While this is an important goal for the project in general i don't think this should be a cartographic goal. We should help newcomers in learning to contribute productively but this is not an education project that adjusts its design goals and standards to the knowledge base of potential contributors.
Collaborator

imagico commented Nov 23, 2016

Changed some formulations based on suggestions by @nebulon42. What i did not change is

  • sentence spacing - i am old fashioned, see https://en.wikipedia.org/wiki/Sentence_spacing.
  • on locally differentiated rendering - that would belong in the more specific guidelines to follow.
  • being easy for new contributors - While this is an important goal for the project in general i don't think this should be a cartographic goal. We should help newcomers in learning to contribute productively but this is not an education project that adjusts its design goals and standards to the knowledge base of potential contributors.

@nebulon42 nebulon42 merged commit cfb2ac2 into gravitystorm:master Nov 23, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@imagico

This comment has been minimized.

Show comment
Hide comment
@imagico

imagico Nov 23, 2016

Collaborator

Thanks - part 2 is in #2462.

Collaborator

imagico commented Nov 23, 2016

Thanks - part 2 is in #2462.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment