docs: reorganize categories

Work on #13
Close #16

Author: molant

docs/browser-engine/browser-engine.md

@@ -5,12 +5,70 @@ slug: /browser-engine
 
 # Overview
 
-Cross-platform technologies that use a browser engine (also called rendering engine) to render
-their UI have been around for many years, more precisely since 2009. Chrome was released the year
-before and it was already the
-fastest browser thanks to its new [V8] JavaScript engine. The web platform is becoming faster and
-sites more interactive. At the same time, iPhone (2007) and Android (2008) devices are becoming more
-and more popular, but it is complicated to find experienced developers, let alone for both.
+Developers of this category use mainly HTML, CSS, and JavaScript to create their applications,
+which are executed on a "browser engine". There are currently 3 actively maintained browser engines:
+
+* [Gecko]
+* [WebKit]
+* [Chromium]
+
+These browser engines power not only "web browsers", but also any technology that uses these
+language to create a User Interface ("Embedded browser engine"). While the foundation might be the
+same, there are some key differences between these two sub-categories.
+
+<!-- Venn diagram of browser engines, web browsers, embedded browser engine -->
+
+## Web browsers
+
+With more than 4 billion internet users and 1.7 billion websites, the web is one (if not the most)
+popular platform.
+
+While websites started as a way to render documents back in 1990, they have come a long way. They
+provide rich experiences with real time communication, video, and 3D graphics. They also adapt
+dynamically to any form factor, work offline, send notifications, and more.
+With all these new features and capabilities, browsers have had to evolve and become more like mini
+OSes, protecting users from malicious attacks and poorly written code.
+
+Tthe [most used ones][statcounter] are [Chrome] ([Chromium]), [Safari] ([WebKit]), and [Firefox]
+([Gecko]). But even though they all are considered modern engines, they are not the same. Even for
+the same browser there can be significant differences accross platforms (more notably on iOS where
+they are force to be a wrapper around the WebKit's WebView).
+
+As with all other technologies, there are pros and cons that developers need to evaluate. The main
+questions to ask are around:
+
+* Feature requirements and platform support
+* Distribution and infrastructure
+
+### Feature requirements and platform support
+
+As mentioned earlier, the Web API has become richer over the last few years. Yet there are features
+that are still not available (nor they will be, like platform specific features).
+
+It is important for developers to know what are the required features and if there is an API to
+enable that. The [capabilities status][Project Fugu] website is a good place to learn about what is
+already available or in development. Not all these APIs are supported by all browsers at the same
+time, so developers need to additionally take into account what does their user base look like, if
+there are alternatives that could be use, or if the experience they are planning could be
+[progressively enhanced][Progressive enhancement] instead of rely entirely on it.
+
+### Distribution and infrastructure
+
+:::caution
+
+This sections needs to be written. Some talking points are:
+
+* _Talk about server vs install file_
+* _Requiring a web server to deliver the app_
+
+:::
+
+## Embedded browser engine
+
+This sub-category has been around since 2009. Chrome was released the year before and it was already
+the fastest browser thanks to its new [V8] JavaScript engine. The web platform is becoming faster
+and sites more interactive. At the same time, iPhone (2007) and Android (2008) devices are becoming
+more and more popular, but it is complicated to find experienced developers, let alone for both.
 
 To fill this opportunity [Apache Cordova] is created (formerly PhoneGap): a mobile development
 platform that uses the platforms’ WebView control (a control that allows you to render web content
@@ -44,7 +102,7 @@ main technical questions can be grouped in the following categories:
 * Hosting language, features and hotpaths
 * Inter-Process Communication layer
 
-## Platform support and Rendering engine
+### Platform support and Rendering engine
 
 At first it can be a bit surprising to group "Platform support" and "Rendering engine". The reason
 is that they are intertwined and one impacts the other (and vice-versa). Technologies that bundle
@@ -54,7 +112,7 @@ Because iOS devices do not allow that, their teams usually limit themselves to d
 to reach more platforms (i.e.: mobile as well), at the expense, in some cases, of quirks between the
 different platforms or if the device is running an older version of the control.
 
-## Hosting language, features and hotpaths
+### Hosting language, features and hotpaths
 
 One common thing to this category is that most of the UI, if not all, is created using web
 technologies (HTML, CSS and JavaScript). But the host could use a completely different language
@@ -76,10 +134,10 @@ A few questions that can help us make a decission are:
   fastest possible version of an algorithm on the host and still have poor results if that
   communication is done in an efficient way.
 
-## Inter-Process Communication layer
+### Inter-Process Communication layer
 
 While there are many browsers and cross-platform technologies, the reality is that there are not
-that many browser enginges (more about this in [Web and PWA]). In fact, most of the technologies
+that many browser enginges as we have seen before. In fact, most of the technologies that render web
 rely on Chromium or WebKit. Unsurprisingly, when using the same engine and the same web content all
 these technologies show similar performance characteristics (memory, processes, threads...). It
 makes sense, the cost of running a browser engine is considerably larger than any “overhead” that
@@ -130,10 +188,20 @@ There are many strategies in here, each one with its pros and cons:
 [Blazor Desktop]: https://devblogs.microsoft.com/dotnet/announcing-net-6-preview-1/#blazor-desktop-apps
 [Capacitor]: https://capacitorjs.com/
 [CEF]: https://bitbucket.org/chromiumembedded/cef/wiki/Home
+[Chromium]: http://www.chromium.org/Home
+[Chrome]: https://www.google.com/chrome/index.html
+[Edge]: https://www.microsoft.com/en-us/edge
 [Electron]: https://www.electronjs.org
 [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
+[Gecko]: https://developer.mozilla.org/en-US/docs/Mozilla/Gecko
+[Firefox]: https://www.mozilla.org/en-US/firefox/new/
 [NW.js]: https://nwjs.io/
+[Progressive enhancement]: https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement
+[Project Fugu]: https://web.dev/fugu-status/
+[Safari]: https://www.apple.com/safari/
+[statcounter]: https://gs.statcounter.com/browser-market-share
 [Tauri]: https://tauri.studio/
+[Types of technologies]: ../types.md
 [V8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine)
-[Web and PWA]: ../web/web.md
+[WebKit]: https://webkit.org/
 [WebSockets]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API

docs/browser-engine/electron.md

@@ -16,7 +16,7 @@ Groups].
 Electron applications use Chromium as the shell to render the User Interface. Developers
 use HTML, CSS and JavaScript to build their apps, which means they can use the libraries and tools
 available to the web community such as React, webpack, Babel, etc. One of the main differences with
-other technologies under the _[browser-engine]_ category, is that JavaScript is used to access the
+other technologies under the _[Browser engine]_ category, is that JavaScript is used to access the
 Operating System features as well. This is because Electron applications come with [Node.js]
 support. At a high-level, [Electron adds the Node.js layer to Chromium's JavaScript engine
 V8][electron-node]. This means that developers can leverate all its ecosystem and also write C/C++
@@ -66,7 +66,7 @@ the needs of a particular company or product.
 | :------------- | :----: |
 | Website | [{{technologies.electron.url}}]({{technologies.electron.url}}) |
 | Platforms | Desktop |
-| Type | [browser-engine] |
+| Type | [Browser engine] |
 | Software type | OSS |
 | License | [MIT] |
 | Copyright | [OpenJS Foundation][electron-foundation] |
@@ -99,7 +99,6 @@ would be Rust, which can be run via [Neon].
 <!-- Ref links -->
 
 [Apple Store policy 2.5.6]: https://developer.apple.com/app-store/review/guidelines/
-[browser-engine]: ./browser-engine.md
 [chrome release cycle]: https://blog.chromium.org/2021/03/speeding-up-release-cycle.html
 [Discord]: https://discord.com/
 [electron-foundation]: https://openjsf.org/blog/2019/12/11/electron-joins-the-openjs-foundation/
@@ -113,5 +112,6 @@ would be Rust, which can be run via [Neon].
 [release timeline]: https://www.electronjs.org/docs/tutorial/electron-timelines
 [Slack]: https://slack.com/
 [Visual Studio Code]: https://code.visualstudio.com/
+[Browser engine]: ./browser-engine.md
 [WhatsApp]: https://www.whatsapp.com/
 [Working Groups]: https://github.com/electron/governance#working-groups

docs/compiled/compiled.md

@@ -0,0 +1,9 @@
+---
+id: overview
+slug: /direct-drawing
+
+---
+
+# Direct drawing
+
+TBD

docs/direct-drawing/direct-drawing.md

@@ -0,0 +1,9 @@
+---
+id: overview
+slug: /platform-controls
+
+---
+
+# Platform controls
+
+TBD

docs/javascript-projection/javascript-projection.md

@@ -4,48 +4,73 @@ title: Types of technologies
 
 # Types of technologies
 
-As mentioned earlier, there are many types of cross-platform technologies. The most common types
-are:
-
-* **[Web]**: Web browsers are available in a wide range of devices (like some smart appliances).
-  While in the past they have been limited on what hardware features they could use, these has
-  change over the last few years thanks to [Progressive Web Apps] and [Project Fugu]: File System,
-  USB, Bluetooth...Not all web browsers implement the same set of features. The browsers based on
-  [Chromium] (like [Chrome] and [Edge]) expose significant more features compared to those based on
-  [Gecko] ([Firefox]) or [WebKit] ([Safari]).
-* **[Browser engine]**: These technologies use a browser engine to render their user interface. This
-  means that HTML, CSS, and JavaScript are most likely the main technologies to drive use
-  interaction. Some examples are [Electron], [Chromium Embedded Framework], [NW.js], [Tauri], etc.
-* **[JavaScript projection]**: In this case, most (if not all) of  the app  logic and UI is written
-  using JavaScript. One significant difference with _Browser engine_ is that instead of using the
-  web DOM to draw the UI, it uses other UI primitives and controls. These primitives and controls
-  could be provided by the Operating System or by another graphical framework. [React Native],
-  [NativeScript], and [NodeGui] are some examples of this category.
-* **[Compiled]**: These technologies have a compilation step that transform the code closer to the
-  CPU. The languages are usually not web related, like C#, Dart, or C++. Some of them use the OS
-  provided controls, while in others they take care of paining all the pixels in the screen. Some
-  examples are [Flutter], [Xamarin], [Qt]
+There are many types of cross-platform technologies. At a high-level, they all work by exposing a
+common API to the developers and then taking care of the underlying specific code for each platform.
+The main difference is where that common API is implemented and what is exposed to the developers.
+It could be an abstraction to how to access common OS features, how to draw in the screen or
+anything in between.
+
+In this website we have decided to categorize the technologies by the type of User Interface (UI)
+rendering strategy. This is the classification we found creates the less groups and overlappin, and
+is easier to rationalize. If you believe there is a better way, please [let us know][GitHub]!
+
+* **[Browser engine]**: This is the category of technologies that use HTML, CSS, and JavaScript to
+  render the UI. This includes not only web browsers, but also any other technology
+  that users a browser engine to render the content (like [Chromium Embedded Framework], [Electron],
+  [Ionic], etc.). There are currently 3 main browser engines that are actively maintained:
+  * [Gecko], used by [Firefox]
+  * [WebKit], used by [Safari]
+  * [Chromium], used by [Chrome]
+
+  While in the past browsers have been limited on what hardware features they could use, these has
+  change over the last few years thanks to [Progressive Web Apps] and [web capabilities
+  project][Project Fugu] (known also as Project Fugu 🐡). Web developers
+  can now access the File System, USB, Bluetooth, and more. It is worth calling out that not all web
+  browsers implement the same set of features. Browsers based on [Chromium] expose significant more
+  features compared to the rest.
+  But there are still features not exposed via the Web API or particular to a given platform. In
+  those situations developers need to look at other technologies that use a browser engine to render
+  the UI but allow direct access to the platform. Some examples of these technologies are [Electron]
+  (used by VS Code), [Chromium Embedded Framework] (used by Spotify), [Apache Cordova], [Ionic],
+  [NW.js], [Tauri], etc.
+
+* **[Platform controls]**: In this category the technology uses the controls (buttons, inputs, etc.)
+  provided by the Operating System, and provides an abstraction to create these interfaces for all
+  the supported platforms. The languages used in this category are diverse. For example,
+  [React Native] and [NativeSript] use JavaScript, [Xamarin] uses C# and/or XAML, and so on.
+  Applications built using these technologies usually adopt the look and feel of the platform where
+  they are running, and thus look different depending on where they are running (e.g.: iOS and
+  Android).
+
+* **[Direct drawing]**: In here, the technologies use low-level APIs provided by the Operating
+  System to draw directly on the screen. This means that they are also responsible for implementing
+  any controls developers might need. For that reason, applications in this category usually have a
+  consistent look and feel regardless of where they are running. Some of the technologies here are
+  [Qt] and [Flutter].
 
 <!-- TODO: Add a diagram representing the above -->
 
+[Apache Cordova]: https://cordova.apache.org/
 [Browser engine]: ./browser-engine/browser-engine.md
 [Chromium]: http://www.chromium.org/Home
 [Chrome]: https://www.google.com/chrome/index.html
 [Chromium Embedded Framework]: https://bitbucket.org/chromiumembedded/cef/wiki/Home
-[Compiled]: ./compiled/compiled.md
+[Direct drawing]: ./direct-drawing/direct-drawing.md
 [Edge]: https://www.microsoft.com/en-us/edge
 [Electron]: https://www.electronjs.org
 [Firefox]: https://www.mozilla.org/en-US/firefox/new/
 [Flutter]: https://flutter.dev/
 [Gecko]: https://developer.mozilla.org/en-US/docs/Mozilla/Gecko
-[JavaScript projection]: ./javascript-projection/javascript-projection.md
+[GitHub]: https://github.com/crossplatform-dev/crossplatform.dev
+[Ionic]: https://ionicframework.com/
 [NativeScript]: https://nativescript.org/
-[NodeGui]: https://docs.nodegui.org/
 [NW.js]: https://nwjs.io/
+[Platform controls]: ./platform-controls/platform-controls.md
+[Progressive Web Apps]: https://web.dev/progressive-web-apps/
+[Project Fugu]: https://web.dev/fugu-status/
 [Qt]: https://www.qt.io/
 [React Native]: https://reactnative.dev
 [Safari]: https://www.apple.com/safari/
 [Tauri]: https://tauri.studio/
-[Web]: ./web/web.md
 [WebKit]: https://webkit.org/
 [Xamarin]: https://dotnet.microsoft.com/apps/xamarin

docs/platform-controls/platform-controls.md

@@ -23,7 +23,7 @@ module.exports = {
           type: 'doc',
           docId: 'intro',
           position: 'left',
-          label: 'cross-platform development',
+          label: 'Why?',
         },
         // {to: '/blog', label: 'Blog', position: 'left'},
         {