[PROJECT] Revamp the Progressive Web Apps documentation

[captainbrosset]

Task list

Update content

Beta Give feedback

1. Go over the steps of the tutorial and add more introduction content, or update the order of articles, as necessary. It goes too quickly into complicated details and should probably start with a high-level description of the demo app.
2. Related: update the app structure article. It's the second one right after the introduction but goes into a complicated description of SSR vs. CSR vs. Streams.
3. Expand on browser support. Maybe turn this into a separate page that displays actual compat tables for the main features.
4. Document the advanced progressive enhancements that PWAs can use.

ToC

Beta Give feedback

1. Fix the sidebar article order to match the order of articles in the tutorial. Create a new custom sidebar for PWA.
2. Figure out whether the "tutorial" (i.e. the set of pages that are linked together with previous/next buttons) needs to be a tutorial. Isn't the sidebar, complemented by well-crafted "see also" sections a better way to navigate?
3. The intro/benefits page should probably be the landing page instead of the current long list of links.
4. The app structure page is a duplicate of the structural overview page.

Generalize content that's too specific

Beta Give feedback

1. De-duplicate the PWA install instructions (1, 2, 3).
2. Make the PWA install instructions less Firefox-only, and update them to how things work today. This content also feels more user-focused than the rest of MDN. This might be better as a separate page, as an appendix or something.
3. Go over docs and avoid mobile-only phrasing/instructions. PWA work on all platforms.

Best practices and benefits

Beta Give feedback

1. Mention the main PWA benefit in the list of advantages: that PWAs can target all devices from a single codebase, which is often more cost-effective than device-specific codebases.
2. Add more "best practice" pages, on top of the performance one, for example about using native-like features such as sharing, badging, shortcuts, protocol handling, background sync, etc.).

Demo app

Beta Give feedback

1. Review the js13kGames 2017 source code, and update it to be current and correct, if needed.

Reference

Beta Give feedback

1. Document missing lang manifest members on manifest page.
2. Document missing file_handlers manifest members on manifest page.
3. Document missing dir manifest members on manifest page.
4. Create a general ref page that lists all ref docs for PWAs.
5. Check if there are any other missing reference docs that need to be created.

Proposal

The PWA documentation mostly lives under the /Web/Progressive_web_apps area, but a lot of the features and APIs used by PWAs are documented in other areas too.

I think the PWA docs are due for an update as they are starting to show signs of aging. My understanding is that it was created a long time ago by different people, and hasn't necessarily been updated since.
Some of the content appears outdated, and some important things are missing.

The PWA technologies are in constant evolution, and adoption of PWA to build apps for mobile and desktop is rapidly increasing.

As part of the OWD steering committee, I mentioned this idea at the weekly SC meeting and people were receptive to the idea of revamping the docs. So I'm filing this proposal to get things started.

---

Below is the current table of content of the /Web/Progressive_web_apps area with some of my own comments:

• Landing page with links
• Multi-page tutorial to learn to build an app, step by step:
  • Intro, what are PWAs, their benefits.
  • App structure, architecture, app shell, streams.
  • Offline with SW.
  • Making PWA installable, the requirements, manifest members, add to home screen, splash screen.
  • Re-engage users, Push notifications.
  • Progressive loading, perf improvements, bundling and splitting, images, on demand loading.
• Structural overview of PWA (duplicate of App structure page in the tutorial).
• Add to home screen, what is it, using beforeinstallprompt (mobile-focused only, Firefox-focused, some outdated desktop info, kind of a duplicate of the tutorial step 4).
• Installing/uninstalling, how to install on multiple browsers (some outdated browser information, and missing desktop support. Also kind of duplicate of the tutorial step 4).

Additional information

For inspiration, here is a look into other PWA documentation websites.

learn.microsoft.com

The PWA docs on learn.microsoft.com are being updated at the moment. The following table of content is the new one:

• Overview/what is it/benefits/store
• Getting started/beginner-style
• Best practices/how to make great apps, especially on desktop
• How to
  • publish to store
  • Debug
  • use in edge
  • try OT/experimental features
• Reference
  • Manifest
  • SW
  • store data
  • icons
    and theme color
  • Badges
  • Notifications
  • Push
  • file handling
  • url handling
  • protocol handling
  • Window Controls Overlay
  • share and share target
  • Shortcuts
  • Widgets
  • background sync
• what's new
• demos

web.dev blog

• Intro
  • what are pwa
  • how pwa can drive business success
  • what makes a good pwa
• make it installable
  • what does it take
  • define installation strategy
• provide installable experience
  • app manifest
  • offline fallback page
  • in-app install experience
  • patterns to promote installation
  • using pwa on Android
• create app-like experience
  • make pwa feel more like an app
  • progressively enhance pwa
• pwa features
  • Shortcuts
  • maskable icons
  • Wco
  • more ways to improve UX
  • is app installed?
  • share and share target
• Advanced
  • how updates to manifest are handled
  • multi-origin pwas
  • multiple pwas on same domain
  • offline design guidelines
• case studies
  • multiple blog posts about products that have transitioned to pwa.

web.dev/learn/pwa

• Landing page with links to other articles
• Intro/best of both worlds/benefits/challenges/compat
• Getting started/tutorial/best practices
• Foundations/responsive/progressive enhancements/perf
• App design/window/icon/theme/display mode/css
• Assets/cache/storage/offline-ready
• Service workers/register/lifecycle/capabilities
• Caching/what to cache/using the API/debugging
• Serving/respond to request/caching strategies
• Workbox
• Offline data/IDB/Storage Manager/FileSystem/Web Storage
• Installation/criteria/desktop and mobile/prompting
• Manifest/register/debug/members
• Installation prompt/beforeinstallprompt
• Update/updating assets/data/service worker/manifest
• Enhancements/shortcuts/iOS splash screen
• Detection/display mode/app installation/related apps
• OS integration/file system/url handling/protocol handling/share/contact picker
• Window management/browsing to other domains/tabs/new windows/WCO/multi-screen
• Experimental features/fugu/OT
• Tools/Device emulation/debugging devtools
• Architecture/SPA vs MPA/streams
• Managing complexity
• Capabilities

Are you willing to support this work?

Yes, I can take an active role in leading/planning/writing docs.

Depends on

No response

[captainbrosset]

As part of this project, we might want to also focus on improving the storage docs too: mdn/content#23557
PWA and storage are not strictly related, you can store data without your site being a PWA, but they're often used together. Something to think about at least.

[wbamberg]

I've been thinking about this with the Divio docs system in mind. We don't often use this system on MDN because 80-90% of our stuff is reference, but it is a very useful model for thinking about doc structure, and is applicable in this case. The site explains it well, but to summarise, it says that docs can be divided into four parts:

• Tutorials: practical lessons that take the learner step by step through the process of building something
• How to: guides that each explain how to achieve a specific thing
• Reference: docs that describe the technical machinery of the thing
• Explanation: guides which focus on developing and deepening understanding of the system.

We don't always have to have all these components, but it's a useful tool to consider which parts we do want, to be conscious about which ones we exclude, and to understand which of the docs we're creating fall into which category. The system also suggests that it's a good idea to avoid docs that blur categories - so for example reference docs should not go deeply into concepts. For example, I think it's a weakness in our docs that pages like https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Offline_Service_workers mix tutorial and explanation. With tutorials people just want to see results.

So in that context, we might think:

• Tutorial would be our step-by-step guide to building a PWA.
• How to could include topics like Define icons and a theme color. But there would be work here to figure out which guides we might want here.
• Explanation could include guides like:
  • what is a PWA (on "what is a PWA", I thought some of the Google docs were confusing because they listed things that I would have thought are just basic requirements of any web app/website (or any software at all really), like performance or accessibility (https://web.dev/learn/pwa/getting-started/#pwa-checklist). This doesn't help me understand what is distinctive about PWAs.)
  • what's the benefit to writing a PWA (versus "normal site"/ versus native app)
  • attributes of PWAs:
    • working offline
    • integrating with the OS
    • running in the background
  • common PWA tech
• Reference should be just a list of links to reference docs elsewhere on MDN, such as:
  • Web Manifest
  • Service workers
  • Notifications API
  • Push API
  • Background Sync API
  • Background Fetch API
  • ...

Like I say we don't need everything here, this is just a framework.

I had a bit of a look through your list of actions, and here are a few notes.

Related: update the app structure article. It's the second one right after the introduction but goes into a complicated description of SSR vs. CSR vs. Streams. If we're trying to get new people to try PWA, this seems likely to confuse them more than it would help them.

Yes, agreed. This seems partly like a consequence of these docs blurring "tutorial" and "explanation".

Fix the sidebar article order to match the order of articles in the tutorial.

I expect that for now we would need a dedicated PWA sidebar. The current sidebar here is a generic one that lists pages in alphabetical order, while of course the tutorial is curated order.

Figure out whether the "tutorial" (i.e. the set of pages that are linked together with previous/next buttons) needs to be a tutorial. Isn't the sidebar, complemented by well-crafted "see also" sections a better way to navigate?

If we want this tutorial to be "building a PWA step-by-step" then next/previous is helpful to emphasise that this is a strongly linked set of pages. It's also pretty common practice in MDN to do this (see also Learn, and tutorials like https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Tutorial).

The intro/benefits page should probably be the landing page instead of the current long list of links.

I'm not sure about this. I think a landing page that shows the scope and organization of the documentation is helpful. It can have a short intro but should mostly be about providing an overview of the docs. I do think it could provide more context than it currently does (for example, explaining which part is a walkthrough of writing a PWA), or it isn't adding any benefit over a sidebar.

Mention the main PWA benefit in the list of advantages: that PWAs can target all devices from a single codebase, which is often more cost-effective than device-specific codebases.

This makes me think we have 2 audiences here: native app developers and web developers, and the story about benefits is different for each. I mean, if I'm right, the "single codebase" benefit is for people coming from a native app world, right? So I think it might be worth being explicit about these two audiences.

Add more "best practice" pages, on top of the performance one, for example about using native-like features such as sharing, badging, shortcuts, protocol handling, background sync, etc.).

A couple of thoughts here. First, the performance page is (again) a mix of doc types. It's primarily part of our "step by step build a PWA" tutorial but includes, again, conceptual stuff on performance. I wonder how much of the conceptual stuff is better covered in general performance docs as it doesn't seem PWA-specific?

Second, perhaps the things you have listed here would be good how to topics?

Review the js13kGames 2017 source code, and update it to be current and correct, if needed.

Yes, definitely!

[estelle]

See doc - https://docs.google.com/document/d/1-skaKXoJ0rKhgBHchTWSTAW5dxrlmVYkPeKUWpet9nE/edit

[captainbrosset]

Will, Estelle, and I met today and discussed about this project, here are some notes, on top of what Estelle already mentioned above:

Sidebar

The PWA docs right now use a generic sidebar.
It's nice because you don't need to create your own one, but it's just alpha ordered right now.
Let's create our own custom sidebar for PWA.

Tutorial

Idea to create 3 little apps for the tutorials:

1. very simple, just one page, just to know how to create an app and make it installable.
2. actual app, but no bells and whistles.
3. use actual pwa features.

Installation docs

Regarding the user documentation about installing PWAs: we should mention this, but it's different in each browser, so perhaps we should link to each vendor's docs.

Ref docs

We should make sure all reference docs are already on MDN. There are 3 missing manifest members, but there may be other missing things too. Updating the list of tasks based on this.

It would be good to also write a reference page that gives links to all reference pages for PWA. Like a cheatsheet.

Table of content

We agreed to start by taking a stab at a new ToC, using the Divio approach mentioned by Will above.

Tutorials: super practical, not conceptual. I want to do this thing, here's how.
How Tos: Sort of like tutorials, but without writing code.
Reference docs: just the API, inputs, outputs.
Explanations: conceptual docs.

[wbamberg]

PWA sidebar -> mdn/yari#8238

[Josh-Cena]

FYI: maybe you would want to look through the following issues

• “Responsive navigation patterns” article needs more examples content#21950
• Content bug: PWA Notification guide only works on desktop browsers. content#9167
• Issue with "Add to Home screen": mention that a 192x192 PNG file is required in the manifest content#8986

[captainbrosset]

Thanks @Josh-Cena. The first and third issues in your list are now closed. Thanks for raising awareness about these.
The second one is something we should try to get to at some point too. I don't think we will do so during the scope of this project, but at some point we should.

[captainbrosset]

Because mdn/yari#9192 landed, this project is officially complete!
We didn't get to everything but enough that the PWA docs are now very useful, and in a state where it's easy to keep adding new guides and how-to articles.
Let me officially close this issue so we can celebrate 😀