Investigate T141304 and, at minimum, document issue
Closed, ResolvedPublic

Description

This ticket relates to T141304, which is about getting all the MAKI symbols. In the Maps Triage meeting, we said "We will investigate and, at a minimum, add user documentation for the issue." I'm not sure who should take on this tasks. @Catrope, can you please assign someone to make a recommendation?

jmatazzoni triaged this task as Low priority.Feb 27 2018, 12:04 AM
jmatazzoni renamed this task from Investigate T141304 and, at minimum, add documentation for the issue to Investigate T141304 and, at minimum, document issue.Feb 27 2018, 10:27 PM

@Pnorman As has been noted (T141304) the documentation for maps sends users interested in using map icons to a list of Maki icons that exists on the Mapbox site. Because their list shows the most recent set, and because we don’t use that most recent set, this makes our documentation wrong. I.e., users can’t get a list of the icons we actually do provide.

Do you know how to find or generate a list of the actual icons we have available? Can you help me with that?

Pnorman added a comment.EditedMar 1 2018, 6:39 PM

This boils down to building the v0.5.0 Maki documentation. I'm not sure what format it outputs, probably HTML which isn't suitable for direct inclusion on a Wiki page. We could either put the resulting HTML page somewhere or export a list of icon name + 12px svg + 18px svg + 24px svg* which could then go into a table on a wiki. There are a total of about 360 SVGs for 120 icons, so adding them to a wiki page sounds painful.

*It's a myth that SVG can be freely scaled. When you change the size of an icon, you change how detailed it can be.

I've built Maki and had a stab at building its documentation. It doesn't work since it relied on Mapbox's specific Jekyll process, but there's not much on the website that an overview image and list won't provide.

https://github.com/mapbox/maki/tree/v0.5.0/www/images has preview images with https://github.com/mapbox/maki/blob/v0.5.0/www/images/maki-sprite.png and https://github.com/mapbox/maki/blob/v0.5.0/www/images/maki-sprite%402x.png (the latter is for Retina use)

The images themselves are in https://github.com/mapbox/maki/tree/v0.5.0/src in SVG form and https://github.com/mapbox/maki/tree/v0.5.0/renders in PNG form

Thanks Paul. So if I understand this correctly, all I really need to do is make a wikitext page that basically reproduces the left column of this page, but adding the actual images. I.e.,

iconname | [image]

The only thing I don't understand is the sizes. Are they allowed in our system? I tried just adding the size numbers in some map examples, e.g., "building-18" or "building-24" instead of just "building," and got a JSON error.

So, either I'm just not using the size setting correctly, or we don't let people pick sizes. Which is it? Which is to say, do we need to show all three sizes on the documentation page? Or just two (if so, which?)? And if it's just one, which one is the one we use?

MaxSem added a subscriber: MaxSem.Mar 6 2018, 10:03 PM

The size is controlled by marker-size, see the spec: https://github.com/mapbox/simplestyle-spec/tree/master/1.1.0

I'd organize it like this

Icon NameSmall (12px)Medium (18px)Large (24px)
bicycle

So we do use all sizes. Good to know. Is there documentation that shows how to specify the icon size?

We added a link to the actual maki symbol list to all the how-to maps pages.

I'm working on updating Map documentation. For icons, what we have available now is a subset of available icons from an older version of Maki. This is already documented. https://www.mediawiki.org/wiki/Maps/Icons

A contributor uploaded the most recent version of Maki icons to Commons.

https://commons.wikimedia.org/wiki/Maki_icons

I was going to update the chart we have to include these icons in the wiki page. Seemed like a good idea.

However, I noticed that for the older version of the icons we use some of the icon names have changed in the newer version - which is what was uploaded to Commons. I note this here so that if we do update the set of icons we change, we don't forget to update the documentation (I wanted to get this out of my head and written down somewhere. ¯\_(ツ)_/¯ )

You an see, from the current set of icons we support, where the names have changed in the new version of Maki (note the redlinks):

https://www.mediawiki.org/w/index.php?title=User:CKoerner_(WMF)/sandbox&oldid=2746814

In T187963#4086075, @CKoerner_WMF wrote:

A contributor uploaded the most recent version of Maki icons to Commons.

https://commons.wikimedia.org/wiki/Maki_icons

I was going to update the chart we have to include these icons in the wiki page. Seemed like a good idea.

However, I noticed that for the older version of the icons we use some of the icon names have changed in the newer version - which is what was uploaded to Commons.

Wait, I'm confused. We talked about simply updating our icon list to the newest. That's what T141304 is about. I thought it was deemed too hard. So what's the story? If all we needed to do was get the symbols into commons, I don't understand why we didn't approve the task to begin with @Pnorman and @Catrope, what is the story here?

@jmatazzoni - please review the following:

For example, "zoo"

current icon new

Questions:
(1) Should we make updated icons available for maps? It'd be nice to resolve T141304: Only a part of MAKI symbols is available (previously map icon "castle" broken).

(2) https://www.mediawiki.org/wiki/Maps/Icons says that

Note: Some icons are not available and the coordinates do not matter. (See task T141304).

  • We should not let users to do some guesswork - if some icons are not available, they should be marked as such or not be on the documentation page. https://www.mediawiki.org/wiki/Maps says: "Maps/Icons - List of possible icons that can be used for location markers in maps" and https://www.mediawiki.org/wiki/Maps/how_to:_maps says: "This page shows examples and names of all markers that work with our maps." It seems there is no reason to have the above statement that some icons are not available.
  • If the coordinates of the icon are changed, the position of the icon will be changed. Does the above statement mean something different?

(3) https://www.mediawiki.org/wiki/Maps/how_to:_maps still says that "Map zoom levels are between 0 (zero) and 18 (eighteen)." (in Good things to know about using map links section)

In terms of "Investigate T141304 and, at minimum, document issue", the task is done. Moving to to Product Review to evaluate whether any follow-ups are needed.

QA recommendation: Product should weigh in.

jmatazzoni closed this task as Resolved.Mar 28 2018, 7:57 PM

Closing this, but I will add T141304 in as a group 4 "maybe," in the event we make more progress than we might have. Unless someone thinks I shouldn't bother?