Request for a reference guide - Offline Caching

[oren]

Preact readme mentions that Preact comes with Auto-generated Service Workers for offline caching powered by sw-precache.

Here are my questions:

1. What performance improvements does it give my users?
2. When does the offine feature kicks in?
3. Are there cases that require modifying the behavior of this feature? What are they and how do you do that?
4. Is there any case where it make sense to disable this feature? What is it and how do you do that?

The answers for those question can be a perfect fit for a reference guide that should be as part of Preact-cli official docs.

Note: @NekR mentioned that on this issues that it might not be needed but I am not sure if he was joking.

[NekR]

@oren just ignore me :-)

[zouhir]

Before opening an issue, please put some effort and research a bit about the topic. The answer for questions 1 and 2 is a top Google Search result: https://developers.google.com/web/fundamentals/getting-started/primers/service-workers\

For questions 3 and 4 I believe Stackoverflow is the right platform and tag it with service-worker - preact-cli

My reply does not represent preact-cli community as I am not a maintainer but I hope it'll help you find more answer quicker and reduce the amount of open issues that are not bugs.

Many thanks @oren

[lukeed]

I find myself agreeing with @zouhir. Many of these questions can be typed directly into a Google search bar & you'll find loads of helpful resources. In particular, Service Worker has been around for quite some time now, so there's definitely no shortage of learning material.

Consolidating all these education materials into a single document is neither the responsibility of preact-cli nor a desired goal. This is here only to get a jumpstart on using these technologies by configuring & setting up the packages for you, the user.

We (or, at least, I) would expect users to know what webpack is, what code-splitting is, what a serviceWorker is, etc, because it's the knowledge of these tools that leads developers to choose one particular "convenience wrapper" over another. Or, at the very least, know enough to know that these are "buzzwords" and just roll with what's given.

Although we're happy to help you when we can in Slack, understand that can't always be there. Similarly, we can't always provide the education or documentation that you're requesting. It takes a lot of time & that's why there are Developer Advocate teams out there who specifically do this. For instance, developers.google.com is an absolutely fantastic resource for many web-related subjects. I would also recommend subscribing to all their YouTube channel playlists.

The above is my personal view on this matter, and is the best advice I can give (as a self-taught developer) to help your accelerated learning too. Nine times out of ten, finding out answers on your own, regardless of the speed or success rate, is faster and more rewarding than waiting for a stranger to answer a question. There has been no better time than now to self-learn anything.

On another note: 3) and 4) will be possible once #56 lands. That is PR for "custom configs" which opens the door for any user-specific changes and customizations.

Thanks and hope that helps!

[oren]

Thanks @zouhir for your reply.

The answer for questions 1 and 2 is a top Google Search result: https://developers.google.com/web/fundamentals/getting-started/primers/service-workers\

The link you provided is the first link in my question.

Mabye I wasn't clear regarding 1 ond 2. I didn't mean 'what are service workers'. What I wanted to understand is in the context of preact-cli, what exactly is implemented when it comes to service workers.

I took the following steps before asking this on github: 1. opened the chrome tab 'Application' and clicked on 'Service Workers'. I clicked on 'Show all' and unregistered everything I saw there. Than I clicked on 'Clear Storage' and 'Clear selected'. I went back to the 'Service workers' tab and hit refresh on http://localhost:8080/ (where my preact-cli app is running) but I don't see anything in this tab.

2. I grepped the preact-cli codebase for the term "sw-precache" (the plugin mentioned in the readme) and found:

new SWPrecacheWebpackPlugin({
  filename: 'sw.js',
  navigateFallback: 'index.html',
  minify: true,
  stripPrefix: config.cwd,
  staticFileGlobsIgnorePatterns: [
    /\.map$/,
    /push-manifest\.json$/
  ]
})

I tried reading the readme of the plugin but it's still not clear to me how exactyl preact-cli using this feature and what is the impact on the user.

You mentioned stackoverflow as the place to ask 3 and 4. I didn't even realize people are using stackoverflow for asking questions about preact-cli! If that's the case, I think we need a section on Preact website and on preact-cli readme that direct people new to the community to the different sources of documentation - slack, issues on github, and stackoverflow.

reduce the amount of open issues that are not bugs

It looks like we think of github issues differently. You assume it's for bugs but I see it also as a way to improve the overall maturity of the documentation around preact and preact-cli. I think it will be helpful to mention on the project's readme not only the different sources of the documentations (slack, github issues, stackoverflow) but also what is the purpose of each one. Doing so will avoid confusion and make clear to new people where is the correct place to ask questions and what kind of questions to ask in each place.

Thanks @lukeed.

Consolidating all these education materials into a single document is neither the responsibility of preact-cli nor a desired goal.

Interesting. Preact is my first real dive into web development and I am helping a few friends that have 0 experience in web development to learn Preact. I actually thought it would be great to make preact-cli's docs, a place that can be friendly not only to performance-minded engineers but also to people new to web development. It does't mean that we should have all the docs inside the repo but at least we can have a few docs with useful links to those who seeks to dive deeper. Basically I am talking about looking at the different feature that are documented as a bullet list on the readme and elaborating a bit more.

Let's take PRPL as example It's mentioned on the readme with a link to what it is but how does preact-cli uses those practices? A markdown file inside a docs folder would be fantastic for this purpose. It can contain something similar to this (with more details):

Render initial route - prerender
Push: serve (by default) creates a simplehttp2server, which is a HTTP2/Push server. You can check the console for verification.
Precache: The service worker is configured for offline use.
Lazy-Load: Automatic code-splitting for routes and shared "chunks" are optimized for reuse. Navigating from /about to /contact will dynamically (or "lazily") load the "contact" bundle and any associated chunks. This is all thanks to webpack.

Another expmple from the readme - 'Monitor your bundle/chunk sizes with built-in tracking'. This sounds amazing and it would be great to understand what built-in tracking means in the context of Preact.

Similarly, we can't always provide the education or documentation that you're requesting. It takes a lot of time & that's why there are Developer Advocate teams out there who specifically do this

Why not use the community members to help document whatever they feel needs it? having a section in preact-cli's readme (or in a docs/contribute.md) about the process for documentation? Doing that will remove the need for 'Developer Advocate teams'. Everyone on slack, github, and stackoverflow can potentially add and tweak existing markdown files. The problem is there are not markdown files yet (:

The community here is very friendly and I am getting a lot of help on slack, but I feel that we should have a place to document some of the answers we get on slack, stackoverflow, and github issues and move it to some official preact-cli docs. That's the best way to scale our community in my opinion.

Let me know what you think.

[lukeed]

What I wanted to understand is in the context of preact-cli, what exactly is implemented when it comes to service workers.

From README: "Auto-generated Service Workers for offline caching powered by sw-precache"

Google: What is SW Precache?

Result: https://github.com/googlechrome/sw-precache

Let's take PRPL as example

This is my point. We didn't create PRPL, nor did we create SW-Precache or Service Worker. We use them in preact-cli and we are happy to debug or investigate any specific bugs or behavior you may find that relates to them... but unfortunately we don't have the capacity to prioritize explaining & teaching them. Their creators will do a better job than we ever could!

For example, Webpack's site/docs are amazing && has a really active StackOverflow community -- I'd recommend looking there for Webpack-related education.

Also, the PRPL technique is pretty advanced. But if you want to learn about each stage, Google Developers is the place to learn that. Our goal (as a CLI) is to implement PRPL on your behalf. However, even though we do a pretty good job at adding it, it'd be a good idea to read their tutorials for a better understanding.

However, once you have learned about these things, the discussion can turn into a "Is there a reason why you did X instead of Y?" as opposed to "Please guide me in learning about X and Y and how they will affect my users."

The first is a much more relevant & useful conversation. The second belongs in Forum:X and Forum:Y. By that same logic, questions about Preact itself belong in the developit/preact repo, right? Although this is a related project, that question would be most appropriate in Preact's home. I'm merely saying the same thing for the other bits & pieces that preact-cli uses.

The only documentation preact-cli needs is verbiage around installation, upgrades, debugging, and usage. Granted, preact-cli is still a WIP, so those features & docs around those features will change over time.

If you'd like to point out weaknesses in those 4 categories, we welcome the suggestions! Better yet, you can get the conversation started faster with a PR and show us changes you think will be most helpful.

But, as the name of the repository suggests, our main & only concern is preact-cli.

Doing that will remove the need for 'Developer Advocate teams'.

I think I can be clearer this time (my bad): A "Developer Advocate" is a full-time job, literally. These are employees (often of Google, Microsoft, Facebook, ...) whose primary job description is to educate other developers of a technology's exciting new features.

This is an open-source project, wherein 100% of us spend some of our free time improving it. We literally & physically cannot take on the role of (professional) Developer Advocates & educate other developers about what our module is built on.

[oren]

Thanks for the lengthy reply! I would love Preact-cli to become more than just an awesome project that bootstrap your PWA and also a destination for learning. I do understand that I might be a minority that would like this dual role (:

I am glad we discussed this. It's was not clear to me what is the goals and direction of this project and community.

[developit]

FWIW I think part of the issue here is that we don't do a good job of linking to other resources for stuff - I think we might link to an article on PRPL, but I'm not sure it's a definitive guide on the topic.

I'm definitely all for improving docs - documentation is one of my weaknesses and that might be at least partly to blame for some Preact projects lacking adequate documentation.

One step we can take here would be to lower the barrier to creating documentation: there is currently no wiki or website for Preact CLI, which means everything has to be terse and in the README. You mentioned a DOCS/ folder, which could work, but I actually think it might be nice to split it up from the code a little more clearly and encourage drive-by collaboration. I'd be fine using Github's wiki functionality to start this off and then maybe migrating it to a section or subdomain on the preactjs.com site. That way we can nicely split up "guide" type documentation from background and context documentation. Thoughts?

[oren]

Sound like a good plan. Whatever we decide, let's make a short description of the type of docs we encourage, and how to contribute. It should be super simple so new people will be able to follow. At least that is my opinion, if you want those docs to be written by anyone and not just a small group of experienced developers.

Also, this is a great read - https://www.divio.com/en/blog/documentation/

Out of the four types mentioned in the article (tutorials, how-to guides, discussions, and reference guides) we have a lot of discussions (slack and GitHub issues) but we are lacking in the other three.

On Jun 21, 2017 7:24 AM, "Jason Miller" notifications@github.com wrote:

FWIW I think part of the issue here is that we don't do a good job of linking to other resources for stuff - I think we might link to an article on PRPL, but I'm not sure it's a definitive guide on the topic.

I'm definitely all for improving docs - documentation is one of my weaknesses and that might be at least partly to blame for some Preact projects lacking adequate documentation.

One step we can take here would be to lower the barrier to creating documentation: there is currently no wiki or website for Preact CLI, which means everything has to be terse and in the README. You mentioned a DOCS/ folder, which could work, but I actually think it might be nice to split it up from the code a little more clearly and encourage drive-by collaboration. I'd be fine using Github's wiki functionality to start this off and then maybe migrating it to a section or subdomain on the preactjs.com site. That way we can nicely split up "guide" type documentation from background and context documentation. Thoughts?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/developit/preact-cli/issues/122#issuecomment-310094705, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAZda5zL7kgCOl7QP8nmqRuEL56Uk9jks5sGSdygaJpZM4N9pvU .

[developit]

That is indeed a good read.

[steve-a-jones]

Completely agree @developit here -- I'm currently using preact-cli and while it is very cutting edge I recognize that it is very early stages as has a lot of room for improvement documentation-wise.

There will always be conflicting perspectives on what responsibilities open source project maintainers should take on, but the existence of issues such as this indicate areas for improvement, which is completely natural.

My preference is to not make too many assumptions about what people know or turn them away ... we are here for a reason and learning. If someone is curious about something and took the initiative to ask a question they are already on the path to deepening their knowledge -- as well as feeling out the community to see if this tool is right for them.

Often, when approaching new tools, it's hard to know which paradigms are being inherited or introduced - I experienced this a lot from the Polymer community and it took a while to make the distinction between Polymer itself and Web Components.

This project rocks and i'm sincerely grateful for the work being done here - let's keep up the good vibes :)

[reznord]

There is a detailed post here - https://github.com/developit/preact-www/issues/152