Add 'What is a PWA' guide

[wbamberg]

Here's a guide to "What is a PWA?". Happy for any kind of feedback, I wasn't sure exactly what I should cover in here or in how much detail.

It has a broken link to an unwritten glossary page to "SDK", which I can write if we agree it's worth doing.

[github-actions]

Preview URLs

• /en-US/docs/Web/Progressive_web_apps/Guides/What_is_a_progressive_web_app

(comment last updated: 2023-05-09 16:41:11)

[estelle]

Suggested change

_Platform-specific apps_ are developed for a specific operating system and/or class of device, like an iOS or Android device, generally using an {{Glossary("SDK")}} provided by the platform vendor. They are usually distributed using the vendor's app store, where the user can find and install them, and they subsequently seem to the user like a permanent extra feature of their device, expanding its capabilities in some way.

_Platform-specific apps_, sometimes referred to as _native apps_, are developed for a specific operating system and/or class of device, like an iOS or Android device, generally using a software development kit (SDK) provided by the platform vendor. They are usually distributed using the vendor's app store, where the user can find and install them, and they subsequently seem to the user like a permanent extra feature of their device, expanding its capabilities in some way.

(and then we can link to glossary page later, if created)
2nd edit was adding "native". Not sure if we want to add that, but I think it will be helpful as they often referred to as native apps and people my search for that term.

[wbamberg]

We had this discussion a few weeks back: both MS and Google guides suggest avoiding this term. I had thought we decided to use "platform-specific apps", in line with web.dev.

The discussion is in Slack though so I can't link to it :(.

[wbamberg]

Also, I think "SDK" is a good candidate for a glossary entry, and am happy to create it if this PR is approved.

[estelle]

Suggested change

	- PWAs can [use the whole screen](Web/Progressive_web_apps/How_to/Create_a_standalone_app), rather than running in the browser UI.
	- PWAs can [use the whole screen](/en-US/docs/Web/Progressive_web_apps/How_to/Create_a_standalone_app), rather than running in the browser UI.

Can we just link to the slug, and it works now? (assuming yes 🎉, so not editing the others and this one can be ignored)

[wbamberg]

um, I think this was a mistake, even though it seems to work... I'll fix it anyway to be on the safe side.

[wbamberg]

Links should be fixed now.

[estelle]

Suggested change

	A PWA must have a web app manifest, and the [manifest must include enough information for the browser to install the PWA](/Web/Progressive_web_apps/Guides/Making_PWAs_installable#the_web_app_manifest).
	A PWA must have a web app manifest, and the [manifest must include enough information for the browser to install the PWA](Web/Progressive_web_apps/Guides/Making_PWAs_installable#the_web_app_manifest).

Github Actions complained about this link. not sure if the slash will fix things as I see some links have a slash and are working.

[estelle]

Looks good!

[estelle]

Suggested change

Service workers encourage an architecture in which the app's pages - that is, the traditional part of a website - implement the user interface, and the service worker implements a backend which can support [offline and background operation](Web/Progressive_web_apps/Guides/Offline_and_background_operation), making the PWA behave more like an app than a website. This is because service workers can be started by the runtime when they are needed (for example, to handle a push notification).

Service workers encourage an architecture in which the app's pages - that is, the traditional part of a website - implement the user interface, and the service worker implements a backend that can support [offline and background operation](Web/Progressive_web_apps/Guides/Offline_and_background_operation), making the PWA behave more like an app than a website. This is because service workers can be started by the runtime, or operating system, when they are needed (for example, to handle a push notification).

a short definition for "runtime" or should we glossary-ize it?

[wbamberg]

I'm not sure what's best here. In other places I've used "browser" but @captainbrosset pointed out that this might confuse people, because it's happening in the background (#25305 (comment)). The point is I suppose that the SW is started from outside the PWA, by "the system" - really whether it's the OS or the browser is an unimportant detail (and I guess for things like Chromebook they might even be the same. But I'm not sure what is good language here. I don't think "runtime" is great but I'm not sure "runtime or OS" is better.

[wbamberg]

Now I see, at the end of that conversation linked above, I said:

I think it might be worth having some text at the start of this page to give this context: talking about how with an installed PWA, the browser is always there orchestrating things even if it's not visible as an app itself (which it is usually not). And that when we say "browser" in this doc that's what we are talking about. What do you think? I would like to merge this guide now as is and work on that in a follow-up, since it will be easier to discuss in a new PR I think.

...but then never followed it up. Maybe this PR is a good place to talk about this, since it's very introductory?

[captainbrosset]

Haha, this is awesome, I just left a review comments about this exact point. I do think we need to do this in this PR. In fact, a little diagram might even help. Something super high-level and simple that shows the different between the browser UI and the browser engine, and that shows that the engine part is in the background and is present in PWAs too.

[captainbrosset]

Regarding the runtime vs. browser vs. system phrasing, I just made a comment about it below (I hadn't seen this comment before reviewing). I'm suggesting to use "browser" here, but only after we've explained that the browser is always the one running the PWA, even if it seems like it's standalone.

[wbamberg]

I have had a go at this: https://pr26569.content.dev.mdn.mozit.cloud/en-US/docs/Web/Progressive_web_apps/Guides/What_is_a_progressive_web_app#pwas_and_the_browser.

[captainbrosset]

I think it'd be good to think of total beginners here and also explain how PWAs actually run. This section clearly explains the benefits of both worlds, but I think the missing piece is understanding that a PWA, even if it looks like a standalone app, still runs in the browser. It's the browser that installs it in the OS, and it's the browser that runs it eventually, even if it may not look like it to the end user.

I think this is important because we very often talk about the browser when talking about PWAs, without really saying why. And as a beginner, or someone coming from a native app background, that might feel weird since we focus so much on building "real" apps that are totally standalone. They might ask themselves: But why do they keep referring to the browser, I only see my app?

In fact, just below, on line 64, we say that the manifest is useful for the browser to install the PWA. So explaining the relationship between the browser and a PWA before that would help clarify this line.

[estelle]

Suggested change

	Traditionally, websites are less like "something the user has" and more like "somewhere the user visits". Typically, a website: does not have a presence on the user's device when the user is not accessing it, can only be accessed by the user opening the browser and navigating to the site, and is highly dependent on network connectivity.
	Traditionally, websites are less like "something the user has" and more like "somewhere the user visits". Typically, a website: does not have a presence on the user's device when the user is not accessing it, and can only be accessed by visiting the site online, which requires network connectivity.

[estelle]

Suggested change

	- **OS integration**: They can be integrated into the host OS: for example, a messaging app can register as a share target, enabling users to select an image in the photo app and send it using the messaging app. They can also access device features such as the camera, GPS or accelerometer.
	- **OS integration**: They can be integrated into the host OS: for example, a messaging app can register as a share target, enabling users to select an image in the photo app and send it using the messaging app. They can also access device features such as the camera, GPS, and accelerometer.

[estelle]

Suggested change

	- The PWA can be installed from platform's app store or installed directly from the web.
	- The PWA can be installed from platform's app store or directly [from the web](/en-US/docs/Web/Progressive_web_apps/Installing).

might be too basic for other pages, but this is a very intro article so we likely want to let them know how to install a PWA

[estelle]

Suggested change

	One basic component of progressive enhancement is that, if the user visits your PWA on the web by entering its URL in a browser, the user can interact with the app like a normal website. But if the browser can install it, the user will be prompted to install it and the app will appear as a new feature on their device.
	One basic component of progressive enhancement is that the application works for all users. When the user visits your PWA on the web by navigating to it, the user should be able to interact with the app as a fully functioning website. If the browser can install it, the progressive enhancement includes the prompt to install the app.

[estelle]

Suggested change

	PWAs should perform feature detection for advanced APIs and provide acceptable fallback experiences.
	The default experience is a fully functioning website, with the PWAs performing feature detection for the advanced APIs that progressively enhance the experience, including the ability to install the app as a PWA.

Or we can change the heading to "Progressive enhancement and graceful degradation."

[estelle]

Suggested change

For example, the [Background Sync API](/en-US/docs/Web/API/Background_Synchronization_API) enables a PWA to ask a service worker to make a network request as soon as the device has connectivity. A classic use case for this is messaging. Suppose the user composes a message, but when the user tries to send the message, the device is offline. The Background Sync API enables the device to send the message in the background once the device is connected. On a device that does not support Background Sync, the app should let the user know the message could not be sent, giving them the chance to try again later.

For example, the [Background Sync API](/en-US/docs/Web/API/Background_Synchronization_API) enables a PWA to ask a service worker to make a network request as soon as the device has connectivity. A classic use case for this is messaging. Suppose the user composes a message, but the device is offline when the user tries to send the message. The Background Sync API enables the device to send the message in the background once the device is connected. On a device that does not support Background Sync, the app should gracefully degrade the user experience, letting the user know the message could not be sent and giving them the chance to try again later.

[captainbrosset]

Great diagram. This helps a lot.

[captainbrosset]

Thank you for adding this section. This is very helpful.

[captainbrosset]

I would personally remove "it's obvious" here. I know it's not what you meant, but it's the sort of phrase I associate with "basic", or "simple" which I tend to stay away from to avoid making assumptions about the reader's level of expertise/understanding of a concept.

Maybe something like:

"When you visit a website in the browser, that website is visible within the UI of the browser, which displays a frame around it with features like back/forward buttons and a title for the page. The source code of the website, and the Web APIs it uses all run in the browser engine."

I would also get rid of "The browser provides a kind of virtual machine for executing the website's code" which I don't think adds much value on top of what's already been said.

[wbamberg]

Fair point about "obvious". But I like the idea that you can see it's "running in the browser". Would you be OK with something like:

When you visit a website in the browser, it's visually apparent that the website is "running in the browser".

?

[captainbrosset]

Suggestion to slightly rephrase "This means they need a browser engine, like Chrome or Firefox, to manage and run them"

"This means they need a browser engine, like the ones in Chrome, Firefox, or Safari, to manage and run them."

Just to make the distinction between browser, browser UI, and browser engine even clearer.