Documentation Overhaul #11966

felixrieseberg · 2018-02-20T00:35:00Z

Apologies for the giant pull request. This is an effort @zeke and I have discussed over and over again and I finally found the time to dig into it.

In essence, this PR takes our existing documentation (everything in the docs/tutorial folder) and creates a clear progression. I have then taken the most obvious holes and filled those in with new documentation. In addition, I have cleaned up all tutorials to use roughly the same style, variable names, and conventions. I also fixed dead links.

This is simply a start. This PR isn't meant to be the end-all of what our documentation looks like, it's merely supposed to be better than what we have today. Today, our documentation is a loose collection of files sorted alphabetically (the "How to build a custom developer tools extension" file comes before the "How to install Electron", because, well, I comes after D...).

📝 Table of contents

In summary:

Also in summary, thanks to @codebytere:

sethlu · 2018-02-20T00:43:25Z

docs/tutorial/boilerplates-and-clis.md

+a look. It's quite popular in the community and uses `electron-builder`
+internally.
+
+## Other Tools and Bboilerplates


Small typo for boilerplate

malept

👍 for the reorganization of the docs

malept · 2018-02-20T01:57:30Z

docs/tutorial/boilerplates-and-clis.md

+
+Forge comes with [ready-to-use templates][forge-templates] for popular
+frameworks like React, Vue, or Angular. It uses the same core modules used by the
+greater Electron community (like [`electron-packager`]) – changes made by


Missing link at the bottom 😄

malept · 2018-02-20T01:59:28Z

docs/tutorial/application-architecture.md

+and renderer processes. Like [`ipcRenderer`](../api/ipc-renderer.md) and
+[`ipcMain`](../api/ipc-main.md) modules for sending messages, and the
+[remote](../api/remote.md) module for RPC style communication. There is also
+an FAQ entry on [how to share data between web pages][share-data].


Missing link

Thanks, fixed!

malept · 2018-02-20T02:01:44Z

docs/README.md

+  * [Using Node.js APIs](tutorial/application-architecture.md#using-node.js-apis)
+  * [Using Native Node.js Modules](tutorial/using-native-node-modules.md)
+  * [Inter-Process Communication](tutorial/application-architecture.md#)
+* [Adding Features to Your App]()


Should this be a link?

malept · 2018-02-20T02:02:49Z

docs/README.md

+  * [Custom Unity Launcher](tutorial/unity-launcher.md)
+  * [Keyboard Shortcuts](tutorial/keyboard-shortcuts.md)
+  * [Offline/Online Detection](tutorial/online-offline-events.md)
+  * [Represented File for macOS Windows](tutorial/represented-file.md)


That is an unfortunately titled document.

Could be changed. What would be a better title?

Felix changed it to "Represented File for macOS BrowserWindows" here (although I don't think it was changed in the file itself).

malept · 2018-02-20T02:15:59Z

docs/tutorial/unity-launcher.md

@@ -0,0 +1,38 @@
+# Unity Launcher Shortcuts


Actions are no longer Unity-specific. They're defined in version 1.1 of the desktop entry spec and they're implemented in the version of GNOME I use (3.22, on Debian).

sethlu · 2018-02-20T02:23:16Z

docs/README.md


-## Tutorials
+____


Wondering if we prefer --- to ____ in the docs

I'd vote for --- too. We use that on the website to denote the "summary" cut-off point for blog posts. It's a carryover convention from Jekyll.

zeke · 2018-02-20T03:15:36Z

@felixrieseberg this is so good it almost makes me want to cry. Thank you so much for moving this forward. I'll review it in earnest tomorrow.

zeke · 2018-02-20T03:18:17Z

docs/tutorial/development-environment.md

+## Setting up macOS
+
+> Electron supports Mac OS X 10.9 (and all versions named macOS) and up. Apple does
+not allow running macOS in virtual machines unless the host computer is already


virtual machines

This blockquote seems like it may not be applicable to the majority of folks who are reading the "Setting up macOS" docs. Seems like more of a concern when it's time to package the app, right?

I've added this because three things kept coming up in my workshops and classes:

People coming in with ancient machines (think Windows XP and 10.8 Macs)

I could usually get those people up and running without replacing their whole machine by giving them a VM

That approach doesn't work on Macs 😢

I'm not married to it though, we can totally take it out.

Fair enough! Leave it in. 👍

YurySolovyov · 2018-02-20T11:43:16Z

docs/tutorial/application-architecture.md

+require compilation of native code before they can be used) will need to be
+compiled to be used with Electron.
+
+The vast majority of Node.js modules is _not_ native. Only 400 out of the


are not ?

YurySolovyov · 2018-02-20T11:44:10Z

docs/tutorial/application-architecture.md

+The vast majority of Node.js modules is _not_ native. Only 400 out of the
+~650.000 modules are native. However, if you do need native modules, please
+consult [this guide on how to recompile them for Electron][native-node] (it's
+easy).


I don't think it's easy thing helps in any way

IMO it makes the docs seem a bit more; friendly 😄

YurySolovyov · 2018-02-20T11:46:12Z

docs/tutorial/application-debugging.md

+Debugging the main process is a bit trickier, since you cannot simply open
+developer tools for them. The Chromium Developer Tools can [be used
+to debug Electron's main process][node-inspect] thanks to a closer collaboration
+between Google / Chrome and Node.js, but you might encounter oddities like


"closer integration between Chrome and Node.js" maybe?

YurySolovyov · 2018-02-20T11:52:09Z

docs/tutorial/development-environment.md

+you will merely need Node.js, npm, a code editor of your choice, and a
+rudimentary understanding of your operating system's command line client.
+
+## Setting up macOS


shouldn't there be on here? Setting up on macOS, Setting up on Windows, etc.

The point is: "Setting up Windows for Electron development" or "Setting up Windows as a developer environment for Electron."

YurySolovyov · 2018-02-20T11:58:59Z

docs/tutorial/first-app.md

+    <h1>Hello World!</h1>
+    We are using node <script>document.write(process.versions.node)</script>,
+    Chrome <script>document.write(process.versions.chrome)</script>,
+    and Electron <script>document.write(process.versions.electron)</script>.


I'm not sure which API is better, but I think we should not encourage using document.write ever.
Maybe use .innerHTML accessor on some tag?

I know that it's real tempting to use this PR to change all our docs, but let's not bikeshed this here - this is the existing electron-quick-start and in the current docs. We can totally improve it, but I think this PR is already big enough that I'd like to focus on the changes.

zeke · 2018-02-20T20:15:24Z

docs/README.md

+  * [Mac App Store](tutorial/mac-app-store-submission-guide.md)
+  * [Windows Store](tutorial/windows-store-guide.md)
+  * [Snapcraft](tutorial/snapcraft.md)
+  * [Supported Platforms](tutorial/supported-platforms.md)


Maybe "Supported Platforms" should be the first page in this section?

zeke · 2018-02-20T20:16:09Z

docs/README.md

+
+## Detailed Tutorials
+
+These individual tutorial expand on topics discussed in the guide above.


plural: tutorials

zeke · 2018-02-20T20:26:01Z

docs/tutorial/application-architecture.md

+```javascript
+const fs = require('fs')
+
+const root = fs.readdirSync('/')


Does this line work on windows? Home about os.homedir() instead?

It does! It returns C:\ by default 👍

zeke · 2018-02-20T20:30:43Z

docs/README.md

+  * [Deploying an Update Server](tutorial/updates.md#deploying-an-update-server)
+  * [Implementing Updates in Your App](tutorial/updates.md#implementing-updates-in-your-app)
+  * [Applying Updates](tutorial/updates.md#applying-updates)
+* [Application Debugging](tutorial/application-debugging.md)


I know you're going off the list I wrote here, but I kinda think the debugging section should come before distribution, security, and updates. And maybe we should give it a name that includes testing, like "Application Testing and Debugging".

malept · 2018-02-20T20:30:53Z

docs/tutorial/linux-desktop-actions.md

+On many Linux environments, you can add custom entries to its launcher
+by modifying the `.desktop` file. For Canonical's Unity documentation,
+see [Adding Shortcuts to a Launcher][unity-launcher]. For details on a
+more generic implementation, see the [Free Desktop Specification][spec].


I would say freedesktop.org specification instead of Free Desktop Specification.

zeke · 2018-02-20T20:31:24Z

docs/tutorial/application-debugging.md

+
+## Renderer Process
+
+The most comprehensive tool to debug individual renderer processes are the


zeke · 2018-02-20T20:33:38Z

docs/tutorial/boilerplates-and-clis.md

+
+That level of modularity and extendability ensures that all developers working
+with Electron, both big and small in team-size, are never restricted in what
+they can or cannot do at any time during their development life-cycle. However,


zeke

Boy howdy! What a great set of additions.

I found a few typos and made a few suggestions. Feel free to dismiss the big requests though, because as you said this PR is intended to be an improvement on what we already have, rather than the be-all end-all of Electron tutorial documentation.

zeke · 2018-02-20T20:34:05Z

docs/tutorial/boilerplates-and-clis.md

@@ -0,0 +1,73 @@
+# Boilerplates and CLIs
+
+Electron development is un-opinionated - there is no "one true way" to develop,


zeke · 2018-02-20T20:36:14Z

docs/tutorial/boilerplates-and-clis.md

+
+A "complete solution to package and build a ready-for-distribution Electron app"
+that focuses on an integrated experience. [`electron-builder`][builder] adds one
+single dependency focuses on simplicity and manages all further requirments


typo: dependency focuses

zeke · 2018-02-20T20:38:02Z

docs/tutorial/development-environment.md

+## Setting up macOS
+
+> Electron supports Mac OS X 10.9 (and all versions named macOS) and up. Apple does
+not allow running macOS in virtual machines unless the host computer is already


Fair enough! Leave it in. 👍

zeke · 2018-02-20T20:41:12Z

docs/tutorial/development-environment.md

+either the latest `LTS` or `Current` version available. Visit
+[the Node.js download page][node-download] and select the `macOS Installer`.
+Once downloaded, execute the installer and let the installation wizard guide
+you through the installation.


I would add a line in here somewhere about how homebrew is not a good avenue for downloading node. I can't remember the exact details but it has something to do with the resultant binary being misnamednodejs, or the install paths being wrong...

zeke · 2018-02-20T20:41:50Z

docs/tutorial/first-app.md

+as a variant of the Node.js runtime that is focused on desktop applications
+instead of web servers.
+
+This doesn't mean Electron is a JavaScript binding to graphical user interface


zeke · 2018-02-20T20:43:48Z

docs/tutorial/first-app.md

+a simple Node application, you would add a `start` script that instructs `node`
+to execute the current package:
+
+```json


I don't feel strongly about it, but this indented JSON style is not consistent what npm does. Any changes like --save would blow this formatting away.

I'm with you. This was in original docs but is easy enough that I fixed it here 👍

zeke · 2018-02-20T20:44:22Z

docs/tutorial/first-app.md

+const electron = require('electron')
+```
+
+The `electron` module exposes is feature in namespaces. The lifecycle of the


typo: exposes is feature

malept · 2018-02-21T18:19:09Z

docs/tutorial/represented-file.md

@@ -0,0 +1,28 @@
+# Represented File for macOS Windows


Could you sync this title with the one in the readme?

felixrieseberg added 22 commits February 19, 2018 12:25

📝 Document development environment

bdc0cd4

📝 Add cli and boilerplate documentation

fc7e50d

📝 macOS Dock documentation

d552af9

📝 Recent documents documentation

8d219e9

📝 Windows Taskbar documentation

3623cf9

📝 Document Unity Launcher

879d21c

📝 Ensure that quick-start.md still exists

d7360e3

📝 Document the first app

ffd607b

📝 Document the app architecture (main/renderer)

c3362c7

📝 Document the progress bar

fe47625

📝 Documenting updates

eeb5845

📝 Some consistency

8dd44f6

📝 A11y documentation

69b0a35

📝 Offscreen Rendering

20ca6b4

📝 Document asar

3c66e81

📝 Installation

e986375

📝 Document debugging

ebbecce

📝 TIE IT ALL TOGETHER

683e02f

📝 Cleanup this hot mess

1914633

📝 Native drag & drop documentation

322f7da

📝 Add missing links

b869471

📝 Fix dead links

64fc523

felixrieseberg requested a review from a team February 20, 2018 00:35

📝 Fix the fix

037ee0c

sethlu reviewed Feb 20, 2018

View reviewed changes

malept reviewed Feb 20, 2018

View reviewed changes

sethlu reviewed Feb 20, 2018

View reviewed changes

zeke reviewed Feb 20, 2018

View reviewed changes

YurySolovyov reviewed Feb 20, 2018

View reviewed changes

❤️ First round of feedback

975e6e6

zeke reviewed Feb 20, 2018

View reviewed changes

malept reviewed Feb 20, 2018

View reviewed changes

zeke reviewed Feb 20, 2018

View reviewed changes

zeke approved these changes Feb 20, 2018

View reviewed changes

❤️ Feedback

9d4c68d

malept reviewed Feb 21, 2018

View reviewed changes

❤️ One more feedback item

c403968

vanessayuenn merged commit 8e51659 into master Feb 21, 2018

vanessayuenn deleted the documentation-overhaul branch February 21, 2018 19:52

This was referenced Feb 27, 2018

Add a sidebar nav to tutorial pages electron/electronjs.org-old#1156

Closed

Organize tutorial content #11416

Closed

zeke mentioned this pull request Mar 20, 2018

add development README #12373

Merged


		## Detailed Tutorials

		These individual tutorial expand on topics discussed in the guide above.


		## Renderer Process

		The most comprehensive tool to debug individual renderer processes are the

		@@ -0,0 +1,73 @@
		# Boilerplates and CLIs

		Electron development is un-opinionated - there is no "one true way" to develop,


		## Tutorials
		____

Documentation Overhaul #11966

Documentation Overhaul #11966

Conversation

felixrieseberg commented Feb 20, 2018 • edited Loading

Choose a reason for hiding this comment

malept left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zeke commented Feb 20, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

YurySolovyov Feb 20, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

felixrieseberg Feb 20, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zeke left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

felixrieseberg commented Feb 20, 2018 •

edited

Loading

YurySolovyov Feb 20, 2018 •

edited

Loading

felixrieseberg Feb 20, 2018 •

edited

Loading