Second pass through examples

[davidtheclark]

The purpose of our first pass was to get more people than just me tinkering with Batfish and testing out the APIs. Now that that's done, we should make a second pass through examples with different goals.

No longer should we throw whatever we want into examples just to see what happens. We should build the examples with the intent to help users understand things. While developing locally we can mess with examples all we want to test what we're doing; but at some point we need to stop committing those messes to the repo.

Based on conversations with @colleenmcginnis @jfurrow @lshig and @samanpwbb, here's a little plan for this second pass:

• Create a series of 3 examples showing increasing levels of usage. Start with a very basic example (maybe our current "basic" that @lshig wrote will do). Add a medium level example (a few more pages and a little more complexity in configuration and usage). And Add a complex example (lots of custom special stuff).
• Focus all other examples on specific, articulable illustrative goals. The existing "internal-routing" and "optimizing-loaders" examples exemplify this example type (hah).
  • Make sure to link to these from relevant passages of documentation.
• Remove the READMEs from each example — instead of following through with that plan, add an annotated table of contents to the examples/README.md file. This will provide better browsing, because users won't have to open an example directory to read its description.

What that plan in mind, here's a list of examples I think we should end up with after our second pass:

Miscellaneous examples — each with a sampling of features:

• [ ] Basic
• [ ] Medium — maybe a blog with an index page
• [ ] Complex

Focused examples — each sharply focused on the thing it's exemplifying:

• [ ] ES5 syntax (@lshig)
• [ ] internal routing
• [ ] Extra Webpack loaders
• [ ] Crazy Webpack configuration, with plugins, loaders, transform functions, file-loader extensions
• [ ] Route change listeners to add a page transition animation and fire analytics events (@jfurrow self-assigned this)
• [ ] Markdown within JS using babel-plugin-transform-jsxtreme-markdown (@lshig)
• [ ] Injecting data into pages (@jfurrow self-assigned this)
• [ ] No configuration (showing that defaults work)

If you're interested in building one of these, please put your name next to it.

cc @mapbox/frontend

[jfurrow]

@davidtheclark These examples sound good. I assigned a couple of them to myself.

[lshig]

I also assigned myself some examples! To clarify, we are implementing basic level examples for each of the focused examples right?

[davidtheclark]

@lshig: I was thinking they'd be like the existing "internal-routing" example — super basic, not even tainted by CSS — just focused on the particular feature.