Meetar/fix tutorials

[meetar]

Turns out pages won't be built unless they are listed in the config hierarchy, which is also used to build the sidebar, which means every page must have an entry in the sidebar.

Ideally the page-building mechanism and the sidebar-building mechanism would be separable, and we'd be able to structure the sidebar in the way that best organizes the content – but we can just move the tutorials here for now.

[meetar]

So precog doesn't like this for some reason – images are broken and none of the pages link.

https://precog.mapzen.com/mapzen/documentation/meetar/fix-tutorials/documentation/tangram#

Does anyone have any idea what's up here?

[rmglennon]

I rebuilt it and it seems happier with the images and navigating the table of contents now.

There were still these two warnings during the build process that I don't quite understand, unless the relative linking is not set up properly.

WARNING - The page "demos.md" contained a hyperlink to "../tutorials/custom-styles.md" which is not listed in the "pages" configuration. WARNING - The page "demos.md" contained a hyperlink to "../tutorials/editing-basemaps.md" which is not listed in the "pages" configuration.

[rmglennon]

https://precog.mapzen.com/mapzen/documentation/meetar/fix-tutorials/documentation/tangram/

^ use this link. It needs to have a / at the end of tangram to make the URLs work.

[kkowalsky]

I've seen that same warning happen with the Android Places API build last week and don't know why that occurs. My initial guess is that the hyperlink is to a page that is in the process of being built and therefore the build isn't suer if it's a real link or might break so we get a warning.

[meetar]

@rmglennon AH HA

Thank you! 💫 😵

[kkowalsky]

A couple of things:

1. Does 'Get Started' make sense at the bottom or should we move it up? Typically this is higher up on the docs navbar.

2. How do we differentiate the Walkthroughs vs tutorials? I think the naming for walkthrough is too similar and we might want to call them something different, perhaps put them underneath setup

3. I'm thinking of having a 'tutorials' subsection in the navbar, but for some reason this creates bullet points in the navbar, that needs to be fixed in the styleguide.

4. Do we still want to call it 'demos' or is there a better name? Let's remove the tutorials section, as that's redundant in the navbar. I'd rather have that gallery page for Tangram rather than putting third party examples in the demos section and link out to that page.

[rmglennon]

A few random comments, agreeing with @kkowalsky's points.

Get started (side note, "Sentence case" is preferred in headings) would usually be at the top with the key info someone needs to use the thing.

"Walkthrough" is something we were kicking around, but the user research subjects said they were pretty much just looking for "tutorial" as the name of page with a series of guided instructions.

The topics in the current "Tutorials" section feel like they could be "tutorials," but perhaps adding step numbers would make them look like the traditional "tutorial" (which is what I'd call the Android and JS "walkthroughs").

I'm also not sure what to do with the Demos page. This could be the landing page when you click on the Get started heading (which is not technically possible yet, but could be the first topic in that section with some content modifications to establish context), or possibly this content be added to the Home tab.

[meetar]

Are there any outstanding issues here? I don't expect this would be the final iteration, but it looks good to me as a starting point, and it would be great to have a base to build from.

[kkowalsky]

Okay, @meetar here's the todo list:

• [x] Look through the tangram.yml and see if there's any thing you don't like about the changes in organizational structure (@meetar)

• [ ] Fix bullet point problem in navbar (@hanbyul-here)

• [x] Do we want to rename Demos? What is its fate? My suggestion is to phase this page out after the examples gallery gets built. The simpler demos could be kept in a tutorial overview page (index.md just for tutorial section). IDK.

• [x] Add in numbered steps for tutorials (@kkowalsky)

[meetar]

Happy with the structure :+1:

Also happy to replace Demos with a gallery once it's there – I'm fine to keep it in here for now as a temporary solution.

[kkowalsky]

kk, just waiting on @hanbyul-here's navbar fix