Make it official

[nebulon42]

@Ircama First thanks for your efforts on documentation!

I'm wondering if we should either reference this from the style or move the relevant parts (if you agree @Ircama) to the Github wiki for osm-carto as this would be an important resource for new contributors.

Of course there are maintainability concerns when including something in the Wiki. It could become easily outdated. But then could at least be edited by anyone.

@gravitystorm @math1985 @pnorman @matkoniecz @kocio-pl @imagico

[Ircama]

@nebulon42 thanks very much indeed!

(if you agree @Ircama)

No problem at all. You are free to take part, edit, reference, copy everything here, as you want.

Of course there are maintainability concerns when including something in the Wiki. It could become easily outdated. But then could at least be edited by anyone.

I often used Liquid include functions in this site and I am not sure they are supported by the wiki. They allow to reuse common sections on different pages and simplify maintenance.

There are also Markdown drawing features and other elements which are very easy to set-up in Github Pages.

I anyway have limited free time to keep everything updated and I have some notes that I still need to publish.

Any suggestion is appreciated.

[nebulon42]

Ok, so it might be best to just link it as resource. But let's wait what others think.

[imagico]

This looks quite useful for people looking for information to get started with various things related to map rendering and style development. However the part specific to openstreetmap-carto seems fairly small, mostly related to the various helper scripts. This might be useful to include as documentation to the project, the rest goes beyond what would make sense to maintain in the project IMO (but still nice work of course).

My own impression regarding the need for instructing material for map rendering and style development based on the toolset used by osm-carto is that the most serious problem is not the lack of hands-on instructions and tutorials written from a user perspective (although this is helpful of course) but the blatant lack of a solid base documentation of many components, especially mapnik and carto. Problems like mapbox/carto#390 seem to result solely from the fact for example that the developers apparently never put down a solid and complete specification how things are supposed to work.

[Ircama]

blatant lack of a solid base documentation of many components, especially mapnik and carto

Exactly. For this reason I would suggest to identify and describe design patterns when possible (even if sometimes they lead to a compromise of functionalities).

Take for instance a discussion in Revised text size for lakes PR. Here the idea of shrinking and re-positioning text size was to avoid of not showing the label of lakes at certain zooms in case of limited space. But for this I was introducing the usage of text-placements. Mapnik has limited rendering of polygon labels (especially concave multi-polygons have issues) and that directive needed testing, e.g. in zones like the one mentioned in water label placement offset. The suggestion to reuse the same text size logic adopted for landcover, was referring to a design pattern at some extent. Related documentation would be useful.