Documentation related to Embedded Mode (or Frontity PHP plugin)

👨‍💻 Framework Development 📖 Documentation
#1

In this PR @mmczaplinski make some points regarding some settings directly related to the Embedded Mode

The current status of the Embedded Mode is this one: Embedded mode & Frontity PHP plugin
And for what I know, there are some other priorities before we can focus on providing a stable version of this feature

From my point of view, we should only add in the docs references to features that are completely available for the final user in a “stable” version (not in a proof of concept from). So, with the information I have, we shouldn’t include any specific references to the Embedded Mode until it’s available for the final user

Maybe, we should include this specific information related to the Embedded Mode in the README.md of the proof-of-concept, or in the FD until the feature (plugin) is released

Or maybe we should release an “experimental” version of the plugin/feature so we can start adding references to it in the documentation

I guess this conversation goes beyond these specific settings related to source.url

So, what do you think? How do you think we should handle the documentation related to this Embedded Mode?

#2

Regarding the Embedded mode and the PHP plugin, we would like to work in the coming months in a really basic plugin, with the basic settings and the current status of the code, to ease the use of it. From there, we will add more functionalities in the future as explain in this thread. We have already tested the proof-of-concept and it has been great so far, so we want to enable other users to use it in production with a basic plugin.

Having said that, I am not sure how this should be handled from the documentation point of view. I think the Embedded mode will be really important when it’s released, so maybe we could start documenting it (or move the readme to the docs), clarifying the status of it. This way we can start referencing it. Something similar to the React Concurrent for example, where they specify that is experimental.

1 Like
#3

Yes, I think we should do something like this.

In order to start documenting it I think it would be better to use the term “Experimental” more than “Proof of Concept” to refer to this Embedded Mode

@luisherranz What do you think about chaningg the name of the repo Frontity Embedded Mode - [Proof of Concept] to something like Frontity Embedded Mode - [Experimental]

I’m using React’s Concurrent Mode as @SantosGuillamot suggests as I think it’s a good reference for this use case

#4

This is my opinion :slightly_smiling_face:

  • I wouldn’t use the proof-of-concept or even experimental names anymore.

  • I would finish the security recommendations that the 10up team did: Issues · frontity/frontity-embedded · GitHub

  • I would add a super simple admin screen so users can enter their Frontity Server URL. Something similar to this:

    image
    image1288Ă—888 32.5 KB

  • I would add a message stating that this plugin is temporary and we will remove it once we release the Frontity WordPress Plugin. Something like this:

    :warning: This plugin is not the final version of the Embedded Mode. The final version will be released as part of the upcoming Frontity WordPress Plugin. Once it’s released, we will remove this plugin. If you want to know about the release you can subscribe to our newsletter at https://frontity.org.

  • I would add a new section to the docs to explain the difference between Decoupled and Embedded modes, with a link to the Embedded plugin. I would repeat the same temporary warning in those docs.

#5

I’d like to add a couple of things to my previous opinion :slightly_smiling_face:

  • I would add a suggestion to use the Simple Cache plugin that supports the REST API for small/medium sites*. I would also add an explanation of how to configure it (turn REST API and Headers options ON).

    * The current version of Simple Cache doesn’t support the REST API. I made a PR to add support (this PR) but Taylor hasn’t reviewed it yet. I would talk with Taylor to see if he has intentions to merge that feature or not. If he doesn’t, I would discuss what to do (fork it…).

  • I would add direct download links for both the Frontity Embedded Mode plugin and the version of the Simple Cache plugin that supports the REST API.

    The thing is that downloads from GitHub include the ref in the folder, for example frontity-embedded-master or simple-cache-master. This is a problem because it can break the plugin (Simple Cache) and the user needs to rename it manually, or can cause problems when updating the plugin if the folder name is not the same. Also, downloading zips from GitHub is not super intuitive, to be honest.

    For those reasons, I would add direct download links to the two plugins so people can download them directly from the docs page.

EDIT: And yet another thing:

  • Document how to use the --public-path option to specify the URL of the static assets, both in development and in production.
#6

Thanks for your feedback @luisherranz
I think those suggestions are great. The thing is doing all of them would require some time to finish them so this documentation related to Embedded Mode would be blocked until then.

What about starting the documentation by applying some of your suggestions while the other ones are properly prioritized and developed

I think we could start documenting the Embedded Mode by applying these suggestions:

My feeling is that, as the Embedded Mode is working successfully in some sites (frontity.org for example) and as it seems to be a recurrent solution when talking with partners and big sites, I think we should start documenting it, in the way it is right now, even with the proper warnings and clarifications about its current status

By the way, what do you think of assigning the Embedded Mode the “alpha” version?
Maybe we can assign to the current status of Embedded Mode some version like embedded-mode-1.0.0-a and work from there

When the plugin and the dashboard are available we can upgrade the version to a “beta” one. Something like embedded-mode-1.0.0-b and work from there

And at some point from there, we can decide to remove the “beta” status to the plugin and start talking of a “stable” version

Software versioning - Wikipedia.

#7

I think I don’t fully understand this suggestion :blush:

Because you also say…

It is correct to assume we should wait until this PR is merged (or a fork is done) before start recommending Simple Cache?

#8

I’ve opened this issue in the docs → "Embedded Mode" documentation as WordPress plugin · Issue #12 · frontity/api-reference · GitHub to do this documentation

I think we should not have references to the Embedded Mode or Frontity plugin in the docs, until a proper documentation about this is added to the docs (so we can link to that page)

In the meantime, we can use this issue to add reminders to add references to the Embedded Mode documentation in other sections of the docs once it’s available

Support for Yoast plugin REST API fields
#9

Sounds like a plan! Thanks Juanma :grinning_face_with_smiling_eyes:

Well… alpha versions are not meant to be used in production… that is the reason I am reluctant to have something called alpha and yet recommend it for production.

Also, both alpha and beta, but even more for beta versions, would mean that “this is almost finished”. When in reality we will remove that plugin and start from scratch with something new.

But I understand why you are suggesting that. Having something that is not final but calling it 1.0 is also confusing.

I don’t have any good idea about how to handle versioning to be honest. My only strong feeling is that if you go with alpha/beta, don’t use alpha, use beta directly. People don’t like to have alpha versions in production :slightly_smiling_face:

Yes, that’s right. We need a resolution before we can start recommending it.