search

pelias / documentation

All things documentation for Pelias
Creative Commons Attribution 4.0 International
229 stars 99 forks source link

Replace most uses of Mapzen words #107

Closed migurski closed 6 years ago

migurski commented 8 years ago

This documentation contains numerous references to the Mapzen Search product, the search.mapzen.com domain, and Mapzen-specific concerns like API keys.

I’m working on a geocoder project for OpenAddresses using Pelias, and I’d like to include this documentation as part of the build process. I would like to modify the documentation here to treat Pelias as a standalone project, and use a post-processing step in mapzen-docs-generator to add the Mapzen-specific words back in.

Does this seem like a desirable change?

orangejulius commented 8 years ago

This sounds awesome, but really hard to do programatically. Can you explain more of what you had in mind?

rmglennon commented 8 years ago

There was much discussion regarding which product name to use, and eventually, we went with Mapzen Search.

Documentation content management systems have the concept of "variables"/"conrefs"/"conditions" that can be dynamically inserted to display the appropriate release number, model number, or product name. GitHub has done this with its docs, depending on whether the help is displaying on the website or enterprise documentation.

More on the process: https://github.com/blog/1939-how-github-uses-github-to-document-github

I'd really like us to be able to implement these because it simplifies the authoring process and adds consistency to reused content. However, this makes the markdown less readable on the GitHub site, and could be confusing if you see the formatted help and then click the "Edit this page on GitHub" button.

migurski commented 8 years ago

Yeah 👍 from me. We may need to write some kind of mkdocs plugin or HTML post-processor to make this real, but I think it’s entirely attainable. It should move hand-in-hand with centralizing certain Mapzen API concerns like rate limiting or authentication.

dianashk commented 8 years ago

Great idea. Would the front-end team own this work, with Pelias updating the docs? Let us know how we can help.

migurski commented 8 years ago

I’m not 100% sure. I think my team can start this with a few innocuous, barely-noticeable edits to test with.

orangejulius commented 6 years ago

This is no longer a hard problem since we can simply search and replace Mapzen/Mapzen Search with pelias thanks to https://github.com/pelias/pelias/issues/703 :)