Add a new display mode How-to page to PWA docs #24709

captainbrosset · 2023-02-21T15:58:22Z

Description

This PR is just one step within the larger PWA docs refresh project: mdn/mdn#280

One of the steps we need to do in this larger project is create a new sidebar, which this PR does not do. @wbamberg is working on in mdn/yari#8238.

This PR adds one new How to page to the PWA docs about display mode.

Motivation

In the PWA docs refresh project, we agreed to create a new How to section that will contain 10 to 20 new pages about many of the features that PWAs can use. Display mode is one of them.

Related issues and pull requests

Related to [PROJECT] Revamp the Progressive Web Apps documentation mdn#280

Next step

Once reviewed and approved, the idea is to merge this in a way that doesn't necessarily appears on MDN just yet. Once we have enough of the new content that we think is useful, we will release the new sidebar and/or landing page to link to the new stuff.

captainbrosset · 2023-02-21T15:59:28Z

Pinging @wbamberg and @estelle who work with me on the project.

github-actions · 2023-02-21T16:01:10Z

Preview URLs

/en-US/docs/Web/Progressive_web_apps/How_to/Display_mode

External URLs (1)

URL: /en-US/docs/Web/Progressive_web_apps/How_to/Display_mode
Title: Create a standalone app

https://web.dev/learn/pwa/app-design/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-03-01 09:38:42)

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

estelle

a lot of feedback.

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

dawei-wang

This may be a good link to add.

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

wbamberg

This looks great Patrick!

My main suggestion is about framing, and relatedly naming.

Ideally the title, and framing, should reflect the question a developer who's trying to build a PWA might have. (We could think of it like: what would they search StackOverflow for: and maybe even mining SO could help us discover and prioritize how-tos.)

My reservation about "How to/choose a display mode" is that "display mode" is a technical term in PWA-land, so if someone knows that, they probably already know about display.

If it were me I would call this something like "Create a standalone app" - although there are other things we can do with display, it seems like standalone is the one most people will be interested in (and of course browser is the default, so there's nothing to do for that case).

Anyway, just a suggestion.

captainbrosset · 2023-02-22T09:43:57Z

Ideally the title, and framing, should reflect the question a developer who's trying to build a PWA might have. (We could think of it like: what would they search StackOverflow for: and maybe even mining SO could help us discover and prioritize how-tos.)

My reservation about "How to/choose a display mode" is that "display mode" is a technical term in PWA-land, so if someone knows that, they probably already know about display.

If it were me I would call this something like "Create a standalone app" - although there are other things we can do with display, it seems like standalone is the one most people will be interested in (and of course browser is the default, so there's nothing to do for that case).

I really like this comment. I did look at SO for a little bit and thought about how to phrase this. But in the end, I think "Create a standalone app" is probably the best we can use. Sure, you can do other things with display, but I think the other most important thing you can do is use minimal-ui which we mention in the article, and which is very close to standalone anyway.

For people learning about PWA as a way to create apps, creating a standalone app is very likely what they will want to learn how to do anyway.

captainbrosset · 2023-02-27T10:44:41Z

@estelle @wbamberg not sure why, but it looks like I can only ask one of you to re-review the PR. Anyway, consider yourself both pinged. When you have some time, please take a look, and let me know if and how we should merge this (considering that this is a new page that doesn't yet have a home in our new PWA doc set).

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

estelle · 2023-03-01T06:09:40Z

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

+browser-compat: html.manifest.display
+---
+
+[Progressive Web Apps](/en-US/docs/Web/Progressive_web_apps) (PWAs) that are installed on a user's device can define how they appear when the user launches them. They can choose to be displayed in a web browser like websites, or have their own dedicated windows similar to how native applications work.


Suggested change

[Progressive Web Apps](/en-US/docs/Web/Progressive_web_apps) (PWAs) that are installed on a user's device can define how they appear when the user launches them. They can choose to be displayed in a web browser like websites, or have their own dedicated windows similar to how native applications work.

Settings in the [web application manifest](/en-US/docs/Web/Manifest) can define how the browser renders installed [Progressive Web Apps](/en-US/docs/Web/Progressive_web_apps) (PWAs) when the user launches them.

I somehow like that my version starts with the term "Progressive Web Apps" and that the thing about the manifest comes after. I think it might be easier for new people to understand it this way.

PWA, which are apps on people's devices, can appear in several ways.

This is done via the app's manifest file.

What do you think?

"Progressive Web Apps" or "Progressive web apps"? Our existing documentation uses the second. web.dev and learn.microsoft.com use the first, so I suppose we should too. Personally I like the second, but consistency is more important.

Also as before, "native" or something else? I think we can always use it here and go back and change when we have decided.

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

wbamberg

Thanks @captainbrosset ! Some of my comments are more like, I wonder what we should do here. Others are more helpful I hope :)

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

wbamberg · 2023-03-04T03:09:31Z

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

+browser-compat: html.manifest.display
+---
+
+[Progressive Web Apps](/en-US/docs/Web/Progressive_web_apps) (PWAs) that are installed on a user's device can define how they appear when the user launches them. They can choose to be displayed in a web browser like websites, or have their own dedicated windows similar to how native applications work.


"Progressive Web Apps" or "Progressive web apps"? Our existing documentation uses the second. web.dev and learn.microsoft.com use the first, so I suppose we should too. Personally I like the second, but consistency is more important.

wbamberg · 2023-03-04T03:10:29Z

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

+browser-compat: html.manifest.display
+---
+
+[Progressive Web Apps](/en-US/docs/Web/Progressive_web_apps) (PWAs) that are installed on a user's device can define how they appear when the user launches them. They can choose to be displayed in a web browser like websites, or have their own dedicated windows similar to how native applications work.


Also as before, "native" or something else? I think we can always use it here and go back and change when we have decided.

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md

wbamberg

👍 this looks awesome, thank you Patrick!

wbamberg · 2023-03-07T05:16:09Z

@estelle , are your comments addressed?

captainbrosset · 2023-03-09T09:28:18Z

As discussed yesterday, this is ready for merging.

Add a new display mode How-to page to PWA docs

26041f3

captainbrosset requested a review from a team as a code owner February 21, 2023 15:58

captainbrosset requested review from hamishwillee and removed request for a team February 21, 2023 15:58

github-actions bot added the Content:Other Any docs not covered by another "Content:" label label Feb 21, 2023

estelle reviewed Feb 21, 2023

View reviewed changes

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md Outdated Show resolved Hide resolved

estelle reviewed Feb 21, 2023

View reviewed changes

dawei-wang reviewed Feb 21, 2023

View reviewed changes

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md Outdated Show resolved Hide resolved

wbamberg reviewed Feb 21, 2023

View reviewed changes

captainbrosset added 3 commits February 22, 2023 10:44

Addressed review comments

c873188

Merge remote-tracking branch 'origin/main' into pwa-display-manifest

8f838fc

Updated the title

7ce287c

captainbrosset requested review from estelle and wbamberg and removed request for hamishwillee and estelle February 27, 2023 10:43

Added compat and spec sections

f810501

captainbrosset mentioned this pull request Feb 27, 2023

Add a new color customization How-to page to PWA docs #24925

Merged

estelle reviewed Mar 1, 2023

View reviewed changes

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md Outdated Show resolved Hide resolved

estelle reviewed Mar 1, 2023

View reviewed changes

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md Outdated Show resolved Hide resolved

estelle reviewed Mar 1, 2023

View reviewed changes

files/en-us/web/progressive_web_apps/how_to/display_mode/index.md Outdated Show resolved Hide resolved

captainbrosset added 2 commits March 1, 2023 10:35

Addressed review comments

d0bfa58

Merge remote-tracking branch 'origin/main' into pwa-display-manifest

f46df37

wbamberg mentioned this pull request Mar 4, 2023

[PWA] Installation guide #25058

Merged

wbamberg requested changes Mar 4, 2023

View reviewed changes

dawei-wang mentioned this pull request Mar 5, 2023

Remove example tags from contribution guide #25093

Merged

captainbrosset added 4 commits March 6, 2023 11:36

Merge remote-tracking branch 'origin/main' into pwa-display-manifest

7fd93e2

Addressed Will's comments

f391056

Fix file path

18f66d8

Fix document path #2

e873328

wbamberg approved these changes Mar 7, 2023

View reviewed changes

captainbrosset mentioned this pull request Mar 7, 2023

Add a new app badge How-to page to PWA docs #25143

Merged

captainbrosset merged commit 9c3e417 into mdn:main Mar 9, 2023

captainbrosset deleted the pwa-display-manifest branch March 9, 2023 09:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a new display mode How-to page to PWA docs #24709

Add a new display mode How-to page to PWA docs #24709

captainbrosset commented Feb 21, 2023

captainbrosset commented Feb 21, 2023

github-actions bot commented Feb 21, 2023 •

edited

estelle left a comment

dawei-wang left a comment

wbamberg left a comment

captainbrosset commented Feb 22, 2023

captainbrosset commented Feb 27, 2023

estelle Mar 1, 2023 •

edited

captainbrosset Mar 1, 2023

wbamberg Mar 4, 2023

wbamberg Mar 4, 2023

wbamberg left a comment

wbamberg Mar 4, 2023

wbamberg Mar 4, 2023

wbamberg left a comment

wbamberg commented Mar 7, 2023

captainbrosset commented Mar 9, 2023

	[Progressive Web Apps](/en-US/docs/Web/Progressive_web_apps) (PWAs) that are installed on a user's device can define how they appear when the user launches them. They can choose to be displayed in a web browser like websites, or have their own dedicated windows similar to how native applications work.
	Settings in the [web application manifest](/en-US/docs/Web/Manifest) can define how the browser renders installed [Progressive Web Apps](/en-US/docs/Web/Progressive_web_apps) (PWAs) when the user launches them.

Add a new display mode How-to page to PWA docs #24709

Add a new display mode How-to page to PWA docs #24709

Conversation

captainbrosset commented Feb 21, 2023

Description

Motivation

Related issues and pull requests

Next step

captainbrosset commented Feb 21, 2023

github-actions bot commented Feb 21, 2023 • edited

estelle left a comment

Choose a reason for hiding this comment

dawei-wang left a comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

captainbrosset commented Feb 22, 2023

captainbrosset commented Feb 27, 2023

estelle Mar 1, 2023 • edited

Choose a reason for hiding this comment

captainbrosset Mar 1, 2023

Choose a reason for hiding this comment

wbamberg Mar 4, 2023

Choose a reason for hiding this comment

wbamberg Mar 4, 2023

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

wbamberg Mar 4, 2023

Choose a reason for hiding this comment

wbamberg Mar 4, 2023

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

wbamberg commented Mar 7, 2023

captainbrosset commented Mar 9, 2023

github-actions bot commented Feb 21, 2023 •

edited

estelle Mar 1, 2023 •

edited