Documentation updates for Mapzen Places

[rmglennon]

Hey @dphiffer @thisisaaronland, here are a few things I've found that we should consider for the Mapzen Places launch. Please go ahead and work through these and I'll review (I'm still trying to figure out the templates), or we can get on a call and we can do them together!

• https://github.com/whosonfirst/whosonfirst-www-api/blob/mapzen/docs/errors.md#mapzen-errors --> change 429 to "Free rate limits or monthly spending limits exceeded"
• https://github.com/whosonfirst/whosonfirst-www-api/blob/mapzen/docs/formats.md reorder to put most common formats at the top (probably geojson?)
• https://github.com/whosonfirst/whosonfirst-www-api/blob/mapzen/docs/index.md -
  • remove any reference to beta or incomplete.
  • suggest the "shout outs" section to be "acknowledgements" and rewritten to allow for better translation from English, and should also reference the data sources in WoF.
  • add some more intro text on what Mapzen Places is and what you can do with it, which we can get from a product page or this list https://mapzen.com/pricing/#places.
• https://github.com/whosonfirst/whosonfirst-www-api/blob/mapzen/docs/methods.md looks good
• https://github.com/whosonfirst/whosonfirst-www-api/blob/mapzen/docs/pagination.md lengthy, but we can review later.
• @kkowalsky also requested we get the https://whosonfirst.mapzen.com/getstarted/ tutorials moved into Mapzen Places.

[thisisaaronland]

I will go over this with @dphiffer in the morning and we will divide up the tasks. As far as the pagination stuff goes, it's not lengthy for the sake of it but only because the future is a lie and we can't have nice things.

As it happens, the Slack people... basically copied everything we said:

https://slack.engineering/evolving-api-pagination-at-slack-1c1f644f8e12?source=collection_home---4------1----------------

[dphiffer]

Hi @kkowalsky, I just committed some updates to the Get Started documentation. I'm not going to deploy them to the live site quite yet, but I'll do that just before launch.

You may need to adjust the <img src="..."> paths according to where images go, but otherwise they should be pretty self-contained.

• https://github.com/whosonfirst/whosonfirst-www/tree/master/content/getstarted/retrievevenues.html
• https://github.com/whosonfirst/whosonfirst-www/tree/master/content/getstarted/retrieveneighbourhoods.html
• https://github.com/whosonfirst/whosonfirst-www/tree/master/www/images/wofspelunkerny.png
• https://github.com/whosonfirst/whosonfirst-www/tree/master/www/images/tutorialmapny.png
• https://github.com/whosonfirst/whosonfirst-www/tree/master/www/images/wofspelunkersf.png
• https://github.com/whosonfirst/whosonfirst-www/tree/master/www/images/tutorialmapsf.png

[kkowalsky]

@dphiffer those updates look :ok, but we do want the tutorial content duplicated onto mapzen.com/documentation/places/tutorials as to allow ease of use for new users.

[rmglennon]

Currently, our docs code requires all content in one help section to be in the same repository. Unfortunately, as @kkowalsky indicated, we'll need to duplicate it in this repository, too, so it shows up in the mapzen.com/documentation site, too.

I've actually never tried to use an .html entry in our docs generator code, but it *should* work because html is valid markdown. Worst case, we might need to give it an .md extension. I'm not sure about the styling, though. I can work on this when the content is in this repo.

[dphiffer]

Yeah, I'd assumed the files would be duplicated. That's fine with me.

[rmglennon]

hey @thisisaaronland - this commit looks great! Thank you

Looks like there might be a neighhourhood typo?

[thisisaaronland]

Thanks - I will fix that shortly, along with any remaining copy.