[doc] add product diagrams (#1360)

* Add image and fix linting problems

* Reduce image size and update content

* Add more content to topic and include image

pwa-devdocs/src/technologies/overview/index.md

@@ -10,26 +10,40 @@ A Progressive Web App, or PWA, is a web application that uses modern web technol
 
 The following features define a basic PWA website:
 
-* **Fast** - PWA sites use a variety of performance optimization strategies to provide a responsive experience or load content fast, even on slow networks.
-* **Secure** - PWA sites use HTTPS connections for enhanced security.
-* **Responsive** - PWA sites implement responsive design strategies to provide a consistent experience on desktops, tablets, and mobile devices. 
-* **Cross-browser compatible** - PWA sites work equally well on all modern browsers, such as Chrome, Edge, Firefox, Safari. 
-* **Offline Mode** - PWA sites cache content to ensure that some content can be served when a user is offline.
-* **Mobile "Install"** - Mobile users can add PWA sites to their home screens and even receive Push notifications from the site.
-* **Shareable content** - Each page in a PWA site has a unique URL that can be shared with other apps or social media.
+-   **Fast** - PWA sites use a variety of performance optimization strategies to provide a responsive experience or load content fast, even on slow networks.
+-   **Secure** - PWA sites use HTTPS connections for enhanced security.
+-   **Responsive** - PWA sites implement responsive design strategies to provide a consistent experience on desktops, tablets, and mobile devices. 
+-   **Cross-browser compatible** - PWA sites work equally well on all modern browsers, such as Chrome, Edge, Firefox, Safari. 
+-   **Offline Mode** - PWA sites cache content to ensure that some content can be served when a user is offline.
+-   **Mobile "Install"** - Mobile users can add PWA sites to their home screens and even receive Push notifications from the site.
+-   **Shareable content** - Each page in a PWA site has a unique URL that can be shared with other apps or social media.
 
 ## What is the Magento PWA Studio project
 
+![pwa studio overview][]
+
 The Magento PWA Studio project is a set of developer tools that allow for the development, deployment, and maintenance of a PWA storefront on top of Magento 2. 
-It uses modern [tools and libraries] to create a build system and framework that adheres to the Magento principle of extensibility.
+It uses modern [tools and libraries][] to create a build system and framework that adheres to the Magento principle of extensibility.
 
 The Magento PWA Studio project provides the following tools:
 
-* **[pwa-buildpack]** - Contains the main build and development tools for a Magento PWA.
-* **[peregrine]** - Contains a collection of UI components for a Magento PWA.
-* **[Venia storefront]** - A proof of concept Magento 2 storefront built using the PWA Studio tools.
-
-[tools and libraries]: {{ site.baseurl }}{% link technologies/tools-libraries/index.md %}
-[pwa-buildpack]: {{ site.baseurl }}{% link pwa-buildpack/index.md %}
-[peregrine]: {{ site.baseurl }}{% link peregrine/index.md %}
-[Venia storefront]: {{ site.baseurl }}{% link venia-pwa-concept/index.md %}
+-   **[pwa-buildpack][] CLI tools** - Contains the main build and development tools for a Magento PWA.
+-   **[Peregrine][] hooks and components** - Contains a collection of UI components and custom React hooks for a Magento PWA.
+-   **[Venia][] store and UI components** - The Venia package contains  proof of concept Magento 2 storefront built using the PWA Studio tools.
+    It also provides UI components you can use in your own projects.
+-   **[UPWARD][]** - A specification for a file that determines the behavior of the application server.
+    The project provides [UPWARD-JS][], which is a JavaScript implementation of an UPWARD server.
+-   **[pwastudio.io][]** - The project provides documentation to help guide developers towards creating a Magento PWA storefront.
+-   **Shared Magento server** - Developers have access to a Magento application running in the Cloud to help jumpstart storefront development.
+    This server contains sample data and is maintained by the team to ensure that you are developing on the latest version of Magento.
+    This shared instance is open to all PWA Studio developers.
+
+[tools and libraries]: {{site.baseurl}}{% link technologies/tools-libraries/index.md %}
+[pwa-buildpack]: {{site.baseurl}}{% link pwa-buildpack/index.md %}
+[peregrine]: {{site.baseurl}}{% link peregrine/index.md %}
+[venia]: {{site.baseurl}}{% link venia-pwa-concept/index.md %}
+[upward]: {{site.baseurl}}{% link technologies/upward/index.md %}
+[upward-js]: {{site.baseurl}}{% link technologies/upward/reference-implementation/index.md %}
+[pwa studio overview]: {{site.baseurl}}{%link technologies/overview/images/pwa-studio-developer-overview.png %}
+
+[pwastudio.io]: https://pwastudio.io

pwa-devdocs/src/technologies/tools-libraries/index.md

@@ -2,15 +2,41 @@
 title: Tools and libraries
 ---
 
+![tools and technology overview][]
+
 To work with the utilities provided by the Magento PWA Studio project, you should be familiar with the tools and libraries listed in the following table:
 
-|                     |                  Contributor                  |              Frontend developer               |       Sysadmin/Devops/Backend developer       |
-| ------------------- | :-------------------------------------------: | :-------------------------------------------: | :-------------------------------------------: |
-| [webpack](#webpack) | <i class="material-icons green">check_box</i> |                                               |                                               |
-| [React](#react)     | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> |                                               |
-| [Redux](#redux)     | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> |                                               |
-| [GraphQL](#graphql) | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> |
-{:style="table-layout:auto"}
+|                           |                  Contributor                  |              Frontend developer               |         Sysadmin/Devops/Backend developer          |
+| ------------------------- | :-------------------------------------------: | :-------------------------------------------: | :------------------------------------------------: |
+| [PHP](#php)               |                                               |                                               | <i class="material-icons warning">help_outline</i> |
+| [JavaScript](#javascript) | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> | <i class="material-icons warning">help_outline</i> |
+| [webpack](#webpack)       | <i class="material-icons green">check_box</i> |<i class="material-icons warning">help_outline</i>                                               |                                                    |
+| [React](#react)           | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> |                                                    |
+| [Redux](#redux)           | <i class="material-icons green">check_box</i> | <i class="material-icons warning">help_outline</i> |                                                    |
+| [GraphQL](#graphql)       | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> |   <i class="material-icons green">check_box</i>    |
+| [Workbox](#workbox)           | <i class="material-icons green">check_box</i> | <i class="material-icons green">check_box</i> |                                                    |
+
+## PHP
+
+[PHP][] is the core language used in the Magento application, but
+it is not one used by the main PWA Studio project.
+In general, you do not need to know PHP to work with PWA Studio tools.
+
+If your storefront requires heavy customizations to the Magento backend, you will need to know PHP to make the necessary backend changes.
+
+## JavaScript
+
+[JavaScript][] is a programming language used to add logic and interactive behaviors to web applications.
+JavaScript is the primary language used in the PWA Studio project, and
+knowing how to develop with it is necessary for using PWA Studio in your own projects.
+
+For frontend development, browser compatibility is important for creating a consistent experience.
+Different web browsers have different version of JavaScript installed, so
+developers should build their applications with this in mind.
+
+For backend developers, scripts and services in PWA Studio are created using [node.js][].
+It is the environment used in the PWA Studio project, but
+it is not a required one for your own projects.
 
 ## webpack
 
@@ -23,6 +49,9 @@ This allows you to extend webpack's functionality beyond JavaScript bundling.
 The [pwa-buildpack][] library contains webpack tools for setting up a development or production environment.
 The configuration for these tools are found in a project's `webpack.config.js` file.
 
+webpack is not a required library for your own projects, but
+it is recommended for the development and performance benefits it provides.
+
 ## React
 
 [React][] officially describes itself as a _JavaScript library for building user interfaces_.
@@ -39,6 +68,16 @@ The library provides the following features that make PWA development easier:
 -   **Modular** - React encourages developers to create modular and reusable UI components.
     Taking a modular approach to development makes your code easier to debug and maintain.
 
+### Hooks
+
+[React hooks][] are a feature introduced in React 16.8.
+They allow the use of state and logic encapsulation without using class components.
+
+Since hooks allow you to store state inside functional components, they are a good alternative to using [Redux](#redux).
+
+The [Peregrine][] library provides custom hooks for common storefront behaviors and logic.
+Developers must be familiar with using hooks to get the most out of the PWA Studo library.
+
 ## Redux
 
 [Redux][] is a JavaScript library used for managing state in a web application.
@@ -48,6 +87,10 @@ Components that plug into the store have direct access to the specific state dat
 
 This library is often paired with React to alleviate the problem of passing data down multiple component layers.
 
+{: .bs-callout .bs-callout-warning}
+Redux is currently being refactored out of the [Venia example storefront][] in favor of [React hooks](#hooks).
+However, Redux is still a valid library for managing state in your own projects.
+
 ## GraphQL
 
 [GraphQL][] is a specification for a data query language on the client side and a service layer on the server side.
@@ -61,10 +104,28 @@ a single GraphQL request returns only the data needed and nothing more.
 Performance is an important metric for PWAs.
 Using GraphQL improves this by reducing the number of server calls and the amount of data returned.
 
+The [Venia example storefront][] uses the [Apollo client][] to fetch data from a GraphQL endpoint, but
+with a little extra work, it is possible to use alternative client libraries in your own project.
+
+## Workbox
+
+Google's [Workbox][] library provides modules that make it easy to work with [service workers][].
+It is useful for boosting performance by controlling cache behavior and enables offline mode, which is a requirement for any Progressive Web Application.
+
 [pwa-buildpack]: {{ site.baseurl }}{% link pwa-buildpack/index.md %}
+[tools and technology overview]: {{ site.baseurl }}{%link technologies/tools-libraries/images/pwa-tools-technology-overview.png %}
+[venia example storefront]: {{site.baseurl}}{% link venia-pwa-concept/index.md %}
+[peregrine]: {{ site.baseurl }}{%link peregrine/index.md %}
 
 [webpack]: https://webpack.js.org/
 [react]: https://reactjs.org/
 [redux]: https://redux.js.org/
 [graphql]: https://graphql.org/
 [rest]: https://en.wikipedia.org/wiki/REST
+[javascript]: https://developer.mozilla.org/en-US/docs/Learn/JavaScript
+[node.js]: https://nodejs.org/en/about/
+[php]: https://php.net/
+[react hooks]: https://reactjs.org/docs/hooks-intro.html
+[apollo client]: https://www.apollographql.com/docs/react/why-apollo/
+[workbox]: https://developers.google.com/web/tools/workbox/
+[service workers]: https://developers.google.com/web/fundamentals/primers/service-workers/