mapzen / documentation Goto Github PK

Currently, the doc pages* say: Get your API key for free access to Mapzen services. Sign in

@louh asked if it should be something else because the site doesn't yet know whether someone is signed in or not. So, “sign in” is actually misleading if a user is already signed in.

Should discuss further.

(* \documentation is a variant of this, and should have the same text)

Felt weird for vector tiles to be missing. The only reason it wasn't there before was because it lived in wikis and readmes (and pre-dated any other doc site work). I copied the content to a folder in mapzen-docs, and will figure out how to reduce duplicated content and get people to modify the content in there later.

I also need to trim down the index topic and make it into multiples, but I added the text so something would be there for it as a placeholder.

Lives in a folder in https://github.com/mapzen/mapzen-docs.

@lou - could you create the config and anything else needed for the build process? I'll go in and update the TOC entries and headings as soon as I have the topic list.

@souperneon - this fixes the five-block uneven issue, so we now have six on the main docs page.

Tagline from developers site is: Add open geospatial data to your applications with the vector tile map service.

• Add headers / footers from main site (copy it over for now)
• Match template to mapzen.com / refer to mockups
• Scrollable side nav fixed on screen, should move out of the way when footer scrolls in
• Improve API key sign up box
• Documentation front page
• Code box gradient - try to fix Chrome aliasing problem

So annoying. Much harder to fix than it seems.

If anyone sees this and wants to attempt a fix, nothing but dragons and shame this way. Sorry.

• Title text is present
• Title text is consistent with product names (for example, Mapzen Turn-by-Turn, rather than Valhalla)
• Page has links to the related project or data page
• Page content and formatting is relatively consistent across products (for example, some have bullet lists, others are paragraphs, or have only a title)
• Title banner across the top is present and consistent (for example, some have wide images, some have gray bar, some have subheadings underneath)
• Search box is present and working
• Breadcrumbs are present and working

Currently, the elevation service docs live under Mapzen Turn-by-Turn, which makes it a bit buried.

Promoting it this way is more of implementation detail because the elevation code lives in Valhalla.

Pull it out into a separate elevation section.

Currently there is nothing on there to explain what the project is and lead into the tutorial in a way.

• Add a blurb about what it is (could be from https://mapzen.com/data/metro-extracts)
• The blurb about getting a key
• Talk about the coverage
• Link to Github to add an extract
• Screenshot of the map

Blurb should tell the users what an API key means, why they need it and how it's free.
Adding a screenshot of the developer section could help or just showing what a sample key looks like, with a link to sign up.

Examples:
Mapbox (https://www.mapbox.com/developers/api/)
Stripe (https://stripe.com/docs/tutorials/checkout)
Shopify (https://docs.shopify.com/api/introduction/getting-started)

https://github.com/mapzen/mapzen-docs-generator/blob/master/config/search.yml

Need to update this to consider renamed and new topics added to pelias/pelias-doc.

(assigning to self)

• Fails to correctly parse keywords, comments, etc consistently
• Fails to identify the language even when it's specified
• Check if hl_lines option works at all

This short page (it's a stub, not done, of course) on Search has problems with scrolling.

To reproduce:

1. Go to http://dev.mapzen.com/documentation/search/getting-started/003-reverse/
2. Use your mouse or keyboard to scroll to the bottom of the page. Currently, this topic has only a heading and no text, so is really short.
3. Scroll back up and notice the TOC and breadcrumbs overlap. The API Key bar may also overlap the TOC. If you scroll up and down enough, it may fix itself.

cc @louh @riordan

Change to:
Main category with the dark blue background and current position on page (sub-category) with the blue line on the left

for instance see generated content for /search/search/
https://github.com/pelias/pelias-doc/blob/master/search.md

CSS word-wrap / overflow-wrap is probably what we want

I imagine this is done in the config file, but wasn't sure about all the consequences of renaming files, so will leave it to the expert...

Currently, the URL, breadcrumbs, and page heading say Valhalla, but we should rebrand this to cover the service name.

Mapzen Turn-by-Turn is pretty long, so I'm open to the URL or breadcrumb being routing or something more generic. (We should try Mapzen Turn-by-Turn first, though.)

Some of these topics are pretty long, and if you scroll to the end of a md file, the TOC won't scroll to the next topic in the TOC. So, you need a way to get back to the top of the page.

We could consider adding a "Back to top" button or keep the breadcrumbs (maybe TOC, too?) displaying on the page as you scroll.

If you scroll a page, the subheadings in a md file in the TOC scroll while the TOC frame stays static on the page. However, when you reach the end of a page, the content page and the TOC both move. Most would expect that TOC would scroll to the next topic (to the next md file).

(I know this is a known issue, but putting it in here so it's documented.)

It looks like this happens if the image is right before a section break?

Example from Valhalla tutorial:
Just before this section: https://github.com/valhalla/valhalla-docs/blob/master/add-routing-to-a-map.md#add-a-map-to-the-page

Since the top banner and project name are prominent on the page, the big red project name is redundant. Let's get rid of that?

On the docs site, when you scroll, the site navigation banner with Mapzen, Projects, etc. stays fixed in place. It has some transparency, so you can see anything underneath it as you scroll.

The banner gets auto-hidden when scrolling on the rest of the Mapzen site.

Consider whether to use /latest or something like that in the URL so it's flexible for when we get a /v2 of certain product.

Makes the last letter look like an r instead of n

This really highlights that we need to rework the headings in the Tangram help, but it does still expose an issue where you can't scroll any further in its current state and entries get cut off.

To reproduce:

1. Open the Tangram help
2. Technical reference > draw section
3. Start scrolling down. Parts of the draw subsection are cut off, as is the shaders section that is at the same level as draw.

These were recommended by GitHub staff and are used in GitHub's own help system.

• html-proofer for links and images: https://github.com/gjtorikian/html-proofer
• write-good for grammar, passive voice, and others: https://github.com/btford/write-good
• pa11y for accessibility: http://pa11y.org/ and https://github.com/nature/pa11y (from Nature)

Apostrophes are missing in the preview, such as "Tangram's styling"
Text with formatting tags, such as backticks, display the tags as spaces, such as "see styles ,"

Looks like it may show just a max number of characters. See if we can control this and be smarter about the text that gets displayed.

Sometimes, you may need to draw attention to a particular line in a code block and show it with different formatting. This came up with respect to tutorials where you include some lines in a code block for context but the user does not need to type all the code in the block.

Kicking around the idea of something like this to :

    <!-- insert this -->
    <link rel="stylesheet" href="leaflet.routing.valhalla.css"/>
    <!-- end insert this -->

This tutorial has an example: http://maptimeboston.github.io/leaflet-intro/ The code you actually type in for a given step is shown with a gray background.

We can use the same one we use on the website

I figure it might be as easy as commenting out these lines, but I'll let @louh do his magic so I don't break anything!

Let's hide until we can get them "refactored", as @riordan said.

• • API Reference:
• • 'Overview': 'swagger-docs/overview.md'
• • 'Paths': 'swagger-docs/paths.md'
• • 'Definitions': 'swagger-docs/definitions.md'

In the Jekyll blog, we can use HTML tags to display a caption under an image and it looks great. In GitHub md and the docs site, the caption class looks the same as the other text, so maybe it just needs different styling?

<p class='caption'>This map shows the default Valhalla routing engine with simplified narration and driving instructions.</p>

Right now, the footer says something like, "Sign up or sign in to get your free API key for unlimited access to Tangram.", although some products don't have a key directly.

How about just, "Get your free API key for unlimited access to Mapzen services."? That makes it work on every page as a generic footer.

Side note, I'm not really keen on the "sign up or sign in" distinction. Sites typically say, "Sign in" and then have a link to create an account if you don't already have one.

Adobe website header:

Click sign in to get this page:

http://dev.mapzen.com/documentation/valhalla/terminology/

The bulleted list is a little hard to read. This is a good place to establish a standard way to do terminology lists and parameters (key value pair lists). I suggest we make the term bold (easy) but ideally we put it in a table so it's super easy to scan and find stuff
Examples:
Shopify (https://docs.shopify.com/api/metafield)
Mapbox (https://www.mapbox.com/developers/api/surface/#parameters)

• Change project names to Playfair (match the h5 style on /projects)
• Change project name in title bar to same style as above

Use background color #385d5c and text color #fff and add in the some description text under the body from /documentation

Currently, the Tangram help has only two top-level entries in the TOC because everything is nested under "concept overviews" and "technical reference". Most of the titles are repeated between these headings (Filters in the overview, and filters in the API section), so it's not as easy as removing the top-level nodes. It would also get really redundant to put a word like "overview" in the first batch of headings or "API/parameter" in the second batch to distinguish them.

We also need to do need to do some work with the H2s and H3s in these topics to reduce the TOC subentries.

For launch, we should do the minimum needed and can go back and work with the Tangram team to clean up the subentries. Ideas on what to do?

Add a witty blurb on top of the page

If you tag some text in a table with backticks, the gray around the text kind of gives a vertical zigzag effect because of the table row shading. Maybe not highlight code text in tables?

Use the outline+transparent button style that we are using for our website

All the md links are broken on the docs site for new content I added yesterday. They work in GitHub, but are not being generated properly with the folder path in mkdocs. Right now, they are missing the hierarchy of documentation/search/topicname and point to documentation/topicname.

For examples, see the Metro Extracts and Search home pages.

Make the order consistent on /projects, /data, /documentation, /developers and the footer

Projects
Tangram
Mapzen Search
Mapzen Turn-by-Turn
Vector Tile Service

Data
Metro Extracts
Borders
Transitland
Who's On First