Frontity Learning Experience & Learning Journey

👨‍💻 Framework Development 📖 Documentation
1

We’ve been talking lately about Learning Experience and Learning Journey, but I think it’s a concept so broad and ambiguous that maybe we all have different ideas about what it is and the actions that should be taken about this.

From DevRel we’re going to start some specific actions to work on this:

  • Brainstorming meetings to decide a better structure in docs
  • Work on specific topics related to Frontity we consider important and create good reference materials to understand them (slides for presentations, demos, doc pages, videos…)

But I would like to know your point of view about this:

  • What should be for you a good Learning Experience for Frontity?
  • What is the most critical thing that right now Frontity is not providing for having a good Learning Experience?
  • If we could only explain 5 topics about Frontity, which ones would they be? (most relevant topics about Frontity)
  • Do you have in mind some references you can provide as an example of a good Learning Experience?

Any other feedback regarding this that is not reflected in the questions will also be appreciated.

Thanks in advance

1 Like
2

From my perspective, one of the most critical resources that we are still lacking is a solid step-by-step tutorial from first principles that explains the most important features of frontity. I think that it should be something similar to the workshop that Michael has given at JSNation, but expanded. Some good examples what I would consider good official beginner tutorials are: https://www.gatsbyjs.com/tutorial/ & https://reactjs.org/tutorial/tutorial.html

3 Likes
3

@mmczaplinski Thanks for your feedback.

What do you think are the most important features of Frontity?

4
  • What should be for you a good Learning Experience for Frontity?

In my opinion, the learning experience starts when a user(s) discovers Frontity and looks for more information about it, and ends when they successfully build a project with it.

This requires:

  • Resources that provide guidance and answer the most common concerns/questions about Frontity so users are well informed, can make better decisions about the framework and easily know if it’s a good fit for their project.

  • When using Frontity: resources that provide support, guidance and reduce the learning curve so users can easily succeed with what they are trying to achieve.

  • What is the most critical thing that right now Frontity is not providing for having a good Learning Experience?

I agree with @mmczaplinski that we are still lacking a solid step-by-step tutorial.

And not sure that this is super critical but I also feel that we should improve how we cover all the new features or packages that we announce (e.g. the analytics packages). If a user who is not part of the community visits the docs, they won’t find any information about these. Until we have some proper docs, maybe we should just create a basic page for them and let users know where to find relevant information/instructions (I don’t know if this the best idea, just throwing a suggestion here).

  • If we could only explain 5 topics about Frontity, which ones would they be? (most relevant topics about Frontity)

Since there are many topics that need to be explained, maybe it makes sense to do the exercise first of thinking about them all and then start prioritizing. Something like Mario and Luis started doing here (see documentation tab) a while ago. This should also help decide decide a better structure of the docs.

1 Like
5

Yes, I agree with this. We should improve the way we’re handling this.
We’ll focus on try to solve this during this Q.

I didn’t know this. Good resource :+1:

6

Hey @juanma thanks for opening this discussion :slight_smile:

From my point of view, the Learning Experience and the Learning Journey are two sides of the same coin. For me it’s easier to think about the “Journey” first, as the “Experience” is how people feel while going through the journey.

What should be for you a Good Learning Experience for Frontity?

Following my previous explanation, a good Learning Experience is the one where the developer has gone through our Learning Journey and is now able to use Frontity Framework successfully without our support (as in asking questions in the community). So from my point of view, we should try to understand how our users want to use Frontity (to create a theme from scratch, to use an existing theme, to create packages for others…) and provide them with a structured journey that covers all the concepts that they need to know in order to achieve their goals with Frontity.

What is the most critical thing that right now Frontity is not providing for having a good Learning Experience?

A unified step by step guide, that goes from the basics to the most complex concepts. So when you follow it, you end up with a project that uses all the Frontity features, and you understand the main concepts. Ideally, this step by step guide should be incremental, so if you need just the basics you can stop at the beginning, and the more you advance the more complex things you can achieve. In this regard, I feel like there’s a big gap between the Getting Started and the Learning Frontity sections of our docs.

I also think that we should create more guides explaining in detail specific use cases of Frontity. These guides could be inspired by the questions frequently asked in the community (Custom Post types, Dynamic Menus, Gutenberg, Performance/Lighthouse, CSS Libraries, WooCommerce, authentication…). Most of these topics have been covered in the Frontity Demos repo or the DevRel talks, but they aren’t easy to find for a newcomer.

Last, I find this article from Gatsby really enriching and related to this conversation, @juanma take a look at it:

If we could only explain 5 topics about Frontity, which ones would they be? (most relevant topics about Frontity)

  1. What is Frontity Framework? What are the advantages of using it? This should also cover the advantages of using Headless, and React over a traditional WP installation
  2. How does Frontity compare with other similar solutions?
  3. How to create a React theme with Frontity from scratch. This could be our step by step guide that covers everything from the basic to the most complicate concepts
  4. How to create, use and re-use Frontity packages
  5. How to deploy a Frontity project

Do you have in mind some references you can provide as an example of a good Learning Experience?

I like the NextJS learn section. I also like a lot the “Getting started with Redux by Dan Abramov”.

I feel like this thread can help us find what are the key things that we want to teach about Frontity. From my point of view, that’s the first challenge to solve. Once we have decided what we want people to learn, then we will be able to start designing the Learning Journey, and afterwards, to review the Learning Experience.

7

I had forgotten about that. Thanks for sharing it Reyes.

8

Great questions! :slightly_smiling_face:

Some of you have mentioned creating resources about creating packages. I think we could divide the learning experience in two targets:

  • People that want to use Frontity to create a theme/site.
  • People that want to create packages for the community.

And in my opinion, I would focus first on the learning experience/journey of theme creators. Once we finish that, we can focus on the learning experience/journey of the extension creators.

I agree with the opinion that it’d be great to have a guide that can be read like a book and teaches you, step by step, all the things you need to know to create your own theme.

I guess that type of book-like guide would have to cover only the “general” or “basic” knowledge. For advanced topics, it’d be better to divide them into individual guides, each one covering one advanced topic. I think people will probably want to learn those advanced topics only one at a time, and only when they need them.

Maybe the initial guide could still mention those “more advanced” guides, so people know that they exist if they need that in the future. It comes to my mind that that could be the case for things like handlers or html2react processors. Right now it’s very difficult to know that you have those advanced APIs available if you need to do more advanced things.

Maybe there should be more sections in the docs, to organize these advanced guides, like:

  • SEO
  • Performance
  • Architectures
  • Deployment
  • TypeScript
  • Multisites
  • Styling
  • AMP
  • Slot and Fills
  • WordPress Data
  • …

Inside each section, we could have different guides, for example inside Architectures I guess there could be things like “Choosing between Decoupled or Embedded mode” or “Understanding Server Side Rendering”. In WordPress data, there could be things like “Custom Post Types” or “Advanced Custom Fields”. And so on.

I’m talking all the time about guides but maybe the format of those guides could be small videos instead of text, like the videos people do in egghead.io or JSforWP.

It’s hard to know. Probably the first thing that is difficult to understand is the “two-step” required to get the WordPress data, having to access state.source.data first and then state.source.post.

I think the ones David and I explained in the WordCamp Sevilla workshop worked well for an introduction. The “two-step” access to data was the only part that I think it was too difficult to understand and we didn’t explain well.

9

This is related to these FD about theme definition

and the conversation he had about Learning & Developer Experience w/ @Pablo & @SantosGuillamot in this meeting → https://www.notion.so/frontity/DevRel-work-Frontity-Learning-Experience-87e1a31eb5f24de0bce35d8acd00f0b4#3d91b7d15c3b4121b428b176afe0597d

I like it :+1:

Michael is working on a course for JS fro WP (Zach) that we think it can be also published for our community

10

I think one of the latest docs I’ve really enjoyed reading are the VIP Go docs.

They are written as if someone was explaining the topic to you, so they are easy and pleasant to read. They also have a lot of simple, broader pages, that link to more specific, in-depth pages. Like this one: https://wpvip.com/documentation/vip-go/caching-on-vip-go/. I think those are great to get a sense of the topic and then click only on the specific topic you’re interested in, instead of having to read over a long page of content until you find the thing you’re looking for :slight_smile:

1 Like
11

I think this is very nicely put, by the way :slight_smile:

This is a big question that I can’t just answer with a list of features :smiley: I think that it’s more of a matter of deciding which features to cut from such an explanation.

By the way, I’ve written a short guideline on documentation a while ago: https://www.notion.so/frontity/Writing-Guideline-107dde0cb57644149eadf828bfdbabdf

There, I mention how I think we should divide the documentation:

Aim for discoverability rather than completeness. The documentation does not have to list every possible option in the API straight away, but rather introduce them slowly and make sure the the user can find those option in the “reference”. Also see next point.

Separate:

  • A hands-on tutorial
  • Conceptual explanations
  • How-to guides / recipes
  • API reference

A nice example of docs that follow this structure are CypressJS docs.

@luisherranz has hinted at dividing the documentation along such lines I think:

So I would suggest going a step further and make a list of all the topics that we already have explained in the docs and then make a list of all the “sections” where we could put those explanations so that we can how we agree on structuring them. Something like:

Key Concepts:

  • reactivity
  • wordpress data
  • modularity (everything is a package)

Guides:

  • SEO
  • typescript
  • Slot and Fill

API reference

  • CLI
  • …@frontity/package
  • frontity WP plugins

I think the forum is a not a good place to keep track such a document because it’s hard to make edits and comemnts on a single version so I think notion or a google doc would be better for collaborating :slight_smile:

1 Like