Discussion: Information architecture for jamstack.org v2

[philhawksworth]

Discussion: Information architecture for jamstack.org v2

A new version of the jamstack.org site is coming. There is already discussion about the planned technical approach which you may be interested in

Goals of this issue

• Share the proposed IA for the next iteration of jamstack.org
• Invite comments from the community to help steer the work and not miss any good insights.
• Decide the high-level content structure for the next release
• Identify any longer term content aspirations

High level content requirements

jamstack.org should:

• Give a clear, concise definition of what jamstack is
• Describe benefits of jamstack
• Pave the way for people to start using jamstack architectures
• Present well organised and discoverable content and resources from the community
• Help people discover and engage with local jamstack communities
• Provide resources to people looking to start a jamstack community group in their own area
• Present a recognisable identity for jamstack which can be easily adopted by all

Proposed high-level content structure

• home
• resources
• examples
• community
  • existing meetups
  • creating a meetup
• Glossary
• Code of conduct

Page purposes

A short description of the purpose of each page in the site structure to help define the requirements for each page type.

Home (/)

• "Onesheet" definition and explantation of what JAMstack is.
• Quickly summarise the primary benefits of jamstack
• Surface recent or highlighted content and resources
• Demonstrate an active community and make it easy to participate
• callout upcoming regional and international events

Resources (/resources)

• Show curated resources from the community
• Demonstrate that there is regularly new content being generated by the community to grow confidence in the adoption
• Publicise visible companies in the ecosystem?

Examples and case studies (/examples)

• showcase examples of jamstack sites
• show both high volume of sites, and also notable implementation, brands, capabilities
• surface tools and technologies used in example sites
• invite contributions from those building jamstack sites and services

Community (/community)

• Inform about the number, and locations of, active meetups
• Give guidance on creating a new meetup. Inform about support for groups
• Advertise upcoming meetup events
• Distribute content from recent meetups
• Promote the community slack to help grow the conversation

Glossary (/glossary)

• Gather definitions of common relevant terms
• Provide clarity and references
• Help combat FUD
• Provide easy process for additional contributions and amends

Code of conduct (/code-of-conduct)

• publish a code of conduct for participant at meetups, and in the slack
• inform participants how to report issues

[tpiros]

I'd like to add two thoughts here the first one is related to the Resources section, the second one is just a general idea

1. Currently I find the resources section a bit hard to navigate so I think it would make sense to drill a little bit down: there are articles/blogposts, video tutorials, e-books and other resources available. Maybe a subpage per resource would be a good solution?

2. I'd love to see a "journey" added. What do I mean by this I hear you ask? Think about a new comer who googles 'what is the jamstack' and lands on this page (which seems to be the official Jamstack page since it's a .org domain). If such a user arrives today, they get some information and two links. I'd work on providing a better user (first-time user) journey. (This means that you can think about different personas as well, not just the first-timers).

[philhawksworth]

Totally with you about the resources page, @tpiros! When this site was first assembled, there were few resources out there. These days they are abundant and so need far better organisation. Perhaps that page might have this sort of structure:

• Resources /resources
  • Videos and presentations
    • Featured - a curated selection of of videos and presentations
    • More videos and presentation → /resources/videos-and-presentations
  • Tutorials and training
    • Featured - a curated selection of of learning resources
    • More tutorials and training → /resources/training
  • Articles
    • Featured - a curated selection of of articles
    • More articles → /resources/articles
  • Add your resources - info on how to add to this list

I'm in favour of having a small number of curated items in each category displayed a little larger than the rest, since this helps make a long list become much more digestible for those trying to get to grips with the content. We could also perhaps rotate those for each view or deploy.

And agreed about the different user needs. Hoping that we can design the content to serve both theses needs, with good summary content, and obvious routes to dig deeper. Always keen to hear thoughts on specifics there. Plus we can consider that lens when we start seeing some content and structure arrive on a staging site soon.

[colbyfayock]

Idea to utilize some cool tech for "demo" purposes: Github Action that deploys at least once daily, the code that generates the features does so at random, so daily it will update with a new random selection.

[philhawksworth]

Yeah I like that @colbyfayock. I suggest that we still have a way to mark a resource or example as "featured" or similar, and then the site generator pulls a random selection from that featured pool at build time.

Regular builds both based on when content is updated, and also once or twice a day is all good.

[tpiros]

That structure looks great @philhawksworth!

Regarding the user journey, I have a few ideas; Not sure how much of it can be implemented. You could have different routes: is the visitor new to Jamstack? Have they used React? Show Next/Gatsby related resources. But I suppose doing it this way you'd end up having a lot of rabbit holes. (Vue > Nuxt, Angular > Scully, JavaScript > 11ty etc etc).

Another approach would be to clearly define each "component" that the Jamstack has. Static site generation, APIs, Markup, security, Hosting & Deployment and link out from each of these sections to more resources.

I'd also add some flowcharts - and more charts/figures in general! I found that using those during my presentations in slides help!

I'd be more than happy to review any documents that you have (if, publicly available) and send feedback :)

[philhawksworth]

Great @tpiros!

Good food for thought here. We already have the example sites contributed tagged with some of the tools that were used on them. Perhaps we can make these tags navigable somehow.

Some charts and diagrams are likely to be useful too. I've also found these very helpful in my own workshops and presentation.

[philhawksworth]

You can see this content structure taking shape in the work in progress along with trying out iteration of the new logo in this site:

https://next--jamstack-site.netlify.com/

More to come.

[tpiros]

This is looking great! How extensive will the glossary section be?

…

On Wed, 8 Apr 2020 at 16:42, Phil Hawksworth ***@***.***> wrote: You can see this content structure taking shape in the *work in progress* along with trying out iteration of the new logo in this site: https://next--jamstack-site.netlify.com/ More to come. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#290 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAPSWXXIH2X4WOIBTJBAWBDRLSD6TANCNFSM4LPGH5SQ> .

[philhawksworth]

Thanks @tpiros!

The glossary will no doubt grow over time. And probably get refined based on discussions and trends. I'll aim to have it populated enough to be a useful starting point, and then grow it over time with help.

[philhawksworth]

Closing this discussion now that the new jamstack.org has launched.
Thanks for all the helpful input everyone.

Specific issues, suggestions, and discussions are of course welcome as the site continues to evolve.