Area for samples on amp.dev

[morsssss]

Background: We want to link to sample mini-sites on amp.dev!

It would be really nice to have this up in time for I/O next week, since I'm doing a talk there on a new sample - AMP CAMP, the e-commerce demo site.

We've already created an area in the amp.dev domain namespace. From now on, samples can be hosted on App Engine and pointed to *.samples.amp.dev. The AMP CAMP site will live at camp.samples.amp.dev.

A couple of sample sites are already beautifully showcased at about/use-cases. But we now have [several samples on github])(https://github.com/ampproject/samples), and this showcase doesn't contain an index.

I think we really need a landing page that features a box for each sample. That box would contain a screenshot, a link to view the mini-site, a link to find the code, and (in a very few cases) an area to describe any guides we've written.

@sebastianbenz points out that we might want to have an area where nondevelopers can easily view these sites, like the current Use Cases section, and an area where programmers can learn how they were made. Hmm.

One option would be to includes the samples in the current Examples area. This area could have three tiers of samples, in ascending order of complexity

1. samples that illustrate the use of an individual component
2. samples that show techniques
3. samples that consist of full webpages or sites

This is possible, but I think it would take reworking this page to make it simpler, as it's already quite full.

I personally like the idea of a new Samples landing page, at least for a short-term solution. We could create a new menu item under "Documentation". This could potentially even be done in time for I/O!

What do you all think?

/cc @matthiasrohmer @sebastianbenz @pbakaus @CrystalOnScript @demianrenzulli @antoinebisch

[matthiasrohmer]

Thanks @morsssss for drafting this out! I think in the long run the samples mentioned should find a home on a reworked samples landing page, just as you mentioned. Also because the current wall of cards is not 100% helpful. But carefully implementing this while creating a good UX will probably require more time than the week left until I/O.

So I'd suggest we head for the extra landing page for a quick solution. Either in the style of the tools page or the Use cases page. As the samples are not that rich in their design I'd vote for the former.

Anyhow I am not to sure about how or if at all we want to integrate the short-term landing page in the navigation as everything with "samples" in the navigation title might be confusing. Would just having a go.amp.dev link serve the purpose already?

[morsssss]

All excellent points!

If at all possible, we'd really like to have at least the new sample linked somewhere on the site for I/O. We could make the quick samples landing page. Or simply add it temporarily to Use Cases, though I'm not sure that makes sense. Perhaps a samples page that was linked from Examples?

[matthiasrohmer]

I ended up starting to add them to the Use cases page. It seems to make sense as the amp-article and amp-concert samples are actually already showcased there. I've been planning to add the smaller ones as teasers below them as you see on the screenshot:

Still, I am not 100% happy... Manually adding them to the current samples landing page again felt strange as they would stand over all other sample cards and therefore might cause confusion - especially if they don't lead to the known samples detail/documentation page.

But: adding actual sample documentation sites for those samples (with playground disabled and preview linking to the glitch/Heroku whatever pages) would work and they would behave like all other samples. What do you all think of that approach?

[sebastianbenz]

I agree with Matthias that we should take some time to properly design this and that it doesn't make sense to rush anything before I/O.

Short term for I/O, I'd suggest:

1. Add the camp demo to https://amp.dev/about/use-cases. The individual samples need to be linkable though.
2. Create a sample landing page in the E-Commerce samples section. This page could be text only as Matthias suggested (here is a sample you can use as a template).

@morsssss how does that sound? Am I missing anything?

[morsssss]

Sure, sounds good to me!

I can create the landing page in the E-commerce samples area if Matthias can design something quick and lovely for Use Cases. @sebastianbenz , I assume you mean another entry under https://amp.dev/documentation/examples/e-commerce/ ? As in, under E-commerce in the sidebar?

[sebastianbenz]

@morsssss exactly

[matthiasrohmer]

Great! @morsssss: the teasers approach for the use cases show above or adding them to the big carousel? And which ones to add?

[morsssss]

Sorry, I'm not quite sure what you mean by "big carousel", since a couple of carousel options have been discussed here during the last couple of weeks!

I do think putting the samples beneath use cases makes them harder to discover. Of course, if you have to scroll past existing use cases to find the new use cases, that's also hard to discover!f

I guess that none of our short-term approaches are ideal, so I don't have a favorite... maybe say more about the big carousel though?

As far as what to add - for I/O, the e-comm demo is the only essential one. Of course it would be wonderful to have something for the Shadow Reader too. And then the other demos.

[morsssss]

Actually, given the time crunch, whatever you do will be fine with me :) We'll work on a longer-term solution in the longer term!

[matthiasrohmer]

Sorry, @morsssss! Forgot to update this here: did you see #2027? I hope this serves your use case for tomorrow - if not let me know!

[morsssss]

Oh, I didn't. I'll look over there... thanks!

[matthiasrohmer]

Now also live at: https://amp.dev/about/use-cases - hope you have a great talk at I/O. 🙂 I'll leave this issue open, as this has only been a stage win and the core problem still exists. Though with a lower priority I guess.

[morsssss]

@matthiasrohmer , @sebastianbenz I'd like to restart this conversation - as I'd like to finish up our various AMP Camp guides in progress and publish them all as part of a new area under Samples. Or in some way! I of course imagine a landing page that contains a screenshot of the site, a link to the code, and a sidebar containing links to various guides.

What do you think?

[sebastianbenz]

Thanks for picking up on this Ben! We should scale this a little bit bigger into a general AMP Demo section listing demos for all the different formats.

How about re-using the Tools template for this?

• re-use the format filter
• define multiple categories (similar to the ones defined in the guides / samples)
• add short preview videos for each of the featured samples.

[morsssss]

A general AMP Demo section would be excellent! Everything you say sounds excellent to me. This assumes, of course, that we have enough demos to fill up a page. The two demos currently under Use Cases would be a start.

The only thing I'd change, if I could, would be to make the large Tools hero area smaller so that the cards for the demos themselves didn't get a little lost down at the bottom.

I assume that also clicking on the AMP Camp demo could then lead to a landing page like we did for the Courses? There, we could host guides.

If you want video, the good news is that I already made a bunch of these for the I/O talk :)

Thanks!

[sebastianbenz]

I think the goal of the page should be to demonstrate what's possible with AMP. This would include samples as well (e.g. amp-position-oberserver, parallax, favorite button, sign-in,...). The Camp Demo, for example, could be listed multiple times for different features (add to cart, product config,...).

For websites we should have enough content. However, we might need to add more for ads, mail and stories.

[sebastianbenz]

Another idea: integrate the demos into a carousel in the about section similar to what we already have on the Stories about page.

https://amp.dev/about/stories/

[morsssss]

A carousel was suggested in the Spring too... and I like both ideas, personally. I suppose it depends on how many demos we have... though of course we could have multiple carousels, each for a different topic.

I do however like the idea of short screencast videos for demos where we have those.

I defer to others on which approach to take!

[morsssss]

But I'd like to choose something and see if we can get it implemented :) What's the best way to decide this, @sebastianbenz ?

[sebastianbenz]

How about starting to collect which demos we want to feature (and which are missing)? I've already created a doc we can use for tracking: https://docs.google.com/spreadsheets/d/1ElIM_WhMnF7ZxOQYTWNLwfO5ACpCSRwqRZTrXNW_jVc/edit#gid=2131671331

I think we should start with the carousel as it's easiest to integrate. Once it becomes too big we can move to a dedicated page.

[morsssss]

Access requested!

I'd like to pursue this for AMP Camp as soon as we can, as my team and I have already written a few of the guides, with more to come. They just need a home!

[sebastianbenz]

@morsssss the guides are not blocked by this. They should go into documentation / samples anyway.