Explain example at the top of the example file

[jill-cardamon]

Following this comment: the examples contain code that is not relevant to understanding the example code's behavior. We should explain the example at the beginning of the example file so developers spend less time looking through example code to find the relevant code for their desired behavior.

/cc: @S2Ler @mapbox/navigation-ios

[1ec5]

The front matter on /ios-sdk could serve as a starting point, but these comments would be more extensive. Should they be formatted as normal text on the site?

/cc @mapbox/docs

[S2Ler]

An example is here: #152

[domlet]

Hi folks!

I don't have in-depth knowledge about particular iOS examples, but I do agree here that it would benefit our developers to:

1. briefly explain each example before the code.
2. simplify example code as much as possible, so developers can more easily recognize the thing being exemplified.

(As is often the case with docs, sometimes writing a short prose description of a thing can often help clarify what should, or should not, be included in the code.)

What is an Example?

From our Docs style guide, all Examples (like the iOS examples mentioned here) should follow these guidelines for the content type:

Mapbox Docs Style Guide > Content types > Example
An example contains an isolated piece of code that showcases how a particular feature is used in practice. An example uses clearly-written code, inline comments, and a concise description that links to relevant documentation to help the user understand what the example is demonstrating and how they can use Mapbox tools to achieve similar results.

How have we improved Examples for other products?

In Jan 2021 we reached a similar conclusion in GL JS docs. While all GL JS examples did have descriptions, many were one-sentence long and included no links to product documentation to help developers recognize how the code was producing a particular outcome. They were sparse and not very developer-friendly.

^ We implemented a test in https://github.com/mapbox/mapbox-gl-js-docs/pull/474 to require that each GL JS example included at least one hyperlink, and we had to update many examples to pass the new test. We should probably do the same with mobile example web pages like this one.

What should we do for iOS Nav examples?

Given that some developers may be browsing the iOS examples directly on GitHub, and not on docs.mapbox.com, I think the team could make a case to include descriptions at the top of each code file...but a better practice might be to include some boilerplate at the top of each example's code, encouraging them to view examples at https://docs.mapbox.com/ios/navigation/examples/:

This code example is part of the Mapbox Navigation SDK for iOS demo app.
To learn more about each example in this app, including descriptions and links 
to documentation, see our docs: https://docs.mapbox.com/ios/navigation/examples/

Then we could apply some tests to all Examples, like this Basic navigation app example to require both a description and at least one hyperlink to help developers find their way into a rewarding relationship with our docs.

Screenshot of the current state of descriptions:

/cc: @mapbox/docs

[S2Ler]

@domlet, Thanks, I'm on board with the proposed change since we use the same approach for other projects. I'll let @mapbox/navigation-ios express their opinion and proceed with the new course if there are no objections or further suggestions.

[domlet]

Cool update for @S2Ler and @pjleonard37 – @colleenmcginnis mentioned yesterday that the iOS examples on docs.mapbox.com now actually pull in example titles and descriptions from the example code:

I have scripts set up in ios-sdk and android-docs to pull in titles and descriptions from whatever table of contents page the product team has set up in their demo app. [for example]:
https://github.com/mapbox/mapbox-navigation-ios-examples/blob/main/Navigation-Examples/Constants.swift