New documentation website

[Dimitar5555]

I am proposing...

A new website that will show tag documentation (and potentially other useful documentation) and better handle translations.

What will this enable that we can't do today?

It will enable us to translate strings faster and have a uniform look of all pages (essentially having templates where translated text is inserted). That way when something changes, related translations can be marked as invalid and sent for an update. It will also improve the user experience.

Whom does this benefit?

Most user will benefit from it.

Any drawbacks?

It may make editing templates harder. Depends on how it's implemented.

Resources needed to build and maintain?

No idea who is going to build it. It will need a database and hosting. If it fully replaces the wiki, it can take it's servers and storage space (respectively run on OSM infrastructure).

Anything else you want to add?

Possible domain could be docs.openstreetmap.org.

See also:

Can't think of any.

Any ideas for a project name?

OSM Docs or OSM Documentation.

Describe this project in a single emoji:

:page_facing_up:

[matkoniecz]

How it differs from osm wiki and data items and id presets and Vespucci presets and JOSM presets?

[Dimitar5555]

It will allow editors to easily translate pages without having to compare what's new and what's missing. Currently there are a lot of pages that have been translated some time ago, then the main pages have been expanded but the translated pages don't get this expansion. Some communities also create their own guides that are better than the English guides but they are not translated back into English. I'm not sure what the presets have to do with this documentation. Can you explain what you mean?

[matkoniecz]

easily translate pages without having to compare what's new and what's missing

That is exactly what data items tried/are trying to achieve.

Before starting massive investment in a new project it would be useful to explain how it is will try to succeed where previous that tried to achieve that failed - and is it opinion shared by others.

I'm not sure what the presets have to do with this documentation

They try to achieve the same goal (describing tags), translation is often involved.

I am not saying that no new projects trying to achieve this should be started but one should take existing attempts into consideration to at least avoid doing the same.

[Dimitar5555]

This project would help translators since each tag and key will have only one name and a single translation thus the enormous amount of duplicated translations should go away. Potential pitfall would be merging all translations from JOSM, iD and the wiki.

[1ec5]

It seems like there are actually two ideas bundled in this issue: unifying presets (and their translations) across editors, and publishing more polished documentation about tags (and presets, presumably).

Unifying presets is the goal of osmlab/editor-presets#1, but it requires buy-in from the various editors that are structured differently, written in different languages, and cater to different audiences with different skill levels and devices. Even if we manage to overcome these difficulties, there’s still the more fundamental issue that presets themselves are a concept bolted onto the side of the OSM ecosystem. For historical reasons, there may be significant pushback against the idea of giving presets a more official status than it currently has compared to raw tags. Over time, the community has become more comfortable with presets in principle, but I think there’s still some disagreement about the role they serve and the legitimate process for coining a new preset.

Data items sidestep all these considerations. They’re nothing more than a structured, machine-readable representation of the infoboxes on the wiki’s tag and value description pages. These qualities make it more easily translatable and queryable. It’s already possible today to publish an alternative presentation of tagging documentation based on data items. In fact, iD uses data items in its ℹ️ panels, and taginfo/taginfo#248 taginfo/taginfo#263 would make the structured data even more discoverable, but a standalone website would be no less feasible. It isn’t necessary to wait for an openstreetmap.org subdomain in order to get such a project off the ground. It might even be possible to implement it using client-side JavaScript on a static site published by GitHub Pages.

[Dimitar5555]

Even if we manage to overcome these difficulties, there’s still the more fundamental issue that presets themselves are a concept bolted onto the side of the OSM ecosystem. For historical reasons, there may be significant pushback against the idea of giving presets a more official status than it currently has compared to raw tags.

It's not about saying which presets should be used and which not. Editors will have the freedom to cherry pick what they want. That will also allow a feedback loop on which editor uses which preset which would help in future deprecation proposals and new tags proposals.

It isn’t necessary to wait for an openstreetmap.org subdomain in order to get such a project off the ground. It might even be possible to implement it using client-side JavaScript on a static site published by GitHub Pages.

That's an interesting idea. I will look into it and what I can do.