Mapbox-gl-js: Write an explanation and include a picture of each layer type in the style spec docs

[lucaswoj]

_From @tmcw on August 16, 2016 14:42_

Right now we don't explain layer types in narrative text. They have names and properties and one can infer from those, but we should be more explicit:

_Copied from original issue: mapbox/mapbox-gl-style-spec#479_

[lucaswoj]

_From @1ec5 on August 16, 2016 19:58_

This would be helpful for the Mapbox iOS SDK, since by design, symbols without documentation comments are completely excluded from documentation, as if they don’t exist.

[1ec5]

The iOS and macOS SDKs are providing their own explanations for the time being:

https://github.com/mapbox/mapbox-gl-native/blob/01b557aeb34d51b2a63ee54ef38192f705d068e9/platform/darwin/scripts/style-spec-overrides-v8.json#L5-L22

These descriptions could be adapted for use with the style specification, although there’s quite a bit of iOS/macOS-specific terminology.

[domlet]

Gathered some images; couldn't resist.

Possible places to add images:

1. https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/ (3x3 grid above the fold?)
2. https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#type (inline beside each explanation?)

[asheemmamoowala]

@domlet Yes!! Can we do it inline for each type in the docs.

For the background layer - a sample image with a pattern might. and non-background showing through could provide more clarity.

[domlet]

Thanks for the guidance @asheemmamoowala – I've tried shoehorning an image into this content here (in the gl-js-docs repo to preview the change), but I'm unable to get hard-coded html to render:

Perhaps @katydecorah can help with shoehorning hard-coded image elements into the style spec, but I think it might be better to add an additional optional property (like doc-img) to enable inline images as part of style-spec documentation, like so:

I think that the ability to add an image into the style-spec would be beneficial, since images make content (especially re: styling) easier to understand.

I don't think the GL JS docs need a parallel doc-img property for items like dragpanhandler but it's worth considering since users traverse a lot between these docs sets, and consistent structure/formatting reduces UX friction.

Would love to know your thoughts!

[katydecorah]

@domlet Do you have a plan for where the images will be hosted? (For example, I would caution against using an image not hosted by Mapbox as the owner could delete it or, in the worst case scenario, replace it with something obscene.)

[domlet]

I'd love to host the images somewhere in mapbox-gl-js or mapbox-gl-js-docs –
@katydecorah I thought I might reach out to you for advice on the architecture.

[asheemmamoowala]

@domlet The content could live in https://github.com/mapbox/mapbox-gl-js-docs/blob/publisher-production/docs/pages/style-spec/layers.md and images be a part of docs so that it's all in one place and easy to maintain?