Diese Seite wurde von der Cloud Translation API übersetzt.

Elektronenprojekt

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:: Elektron
Technischer Redakteur:: Mister Gold
Projektname:: Electron-Anleitung
Projektdauer:: Standardlänge (3 Monate)

Projektbeschreibung

PROJEKTZUSAMMENFASSUNG

Electron ist eines der beliebtesten Tools zum Erstellen plattformübergreifender Desktop-Apps mit JavaScript, HTML und CSS. Eine Sammlung von Apps, die mit Electron erstellt wurden, umfasst fast 900 Einträge und diese Liste wächst kontinuierlich. Einige der beliebtesten Entwicklertools wie Visual Studio Code, Atom, Postman, Slack und GitKraken basieren auf Electron.

Die Beliebtheit von Electron liegt an der einfachen Lernkurve und der niedrigen Einstiegsschwelle: Jeder, der JavaScript, HTML und CSS beherrscht, kann seine eigene Anwendung erstellen. Aufgrund der enormen Wachstumsraten ist es notwendig, Anleitungen und Einstiegsleitfäden zu erstellen, die leicht verständlich und einfach zu bedienen sind.

Ziel des Projekts ist es, Anwendungsentwicklern, die das Electron-Framework noch nicht kennen, Vertrauen zu vermitteln und ihnen eine einheitliche und optimierte Entwicklung ihrer eigenen Electron-Anwendungen von Grund auf zu ermöglichen.

Projektprobleme

Nachfolgend finden Sie eine Liste der wichtigsten Probleme im Zusammenhang mit der Dokumentation zu Electron-Anleitungen: 1. Unklarer Ausgangspunkt und nicht intuitive Einführungsinformationen zu den Schritten der Anwendungsentwicklung 2. Verstreute und redundante Informationen zum Prozess der Anwendungsentwicklung 3. Unorganisierte Anleitungen für den Einstieg ohne einheitliche „Source of Truth“

PROJEKTANGEBOT

Entsprechend dem Ziel des Projekts und den oben beschriebenen Problemen finden Sie hier eine Liste der vorgeschlagenen Verbesserungen: 1. Aktualisieren Sie die vorhandenen Anleitungen. Damit die ersten Schritte reibungslos und einheitlich ablaufen, sollten die folgenden Dokumente aktualisiert werden, wobei der Wechsel von einfach zu komplex schrittweise erfolgen sollte: - Entwicklerumgebung - Erste Electron-App schreiben - Funktionen zu Ihrer App hinzufügen (Zusammenfassungsseite erstellen) - App-Verpackung und -Verteilung 2. Strukturieren Sie das Dokumentationsverzeichnis neu. Damit neue Entwickler sehen können, was für den Einstieg unerlässlich ist und was als weitere Schritte betrachtet werden kann, sollte die Seite mit der Dokumentation sowohl visuell als auch kontextuell in Schritte unterteilt sein, um die erste Anwendung so schnell wie möglich online zu stellen. Die Umstrukturierung umfasst auch eine Anleitung zu den möglichen nächsten Schritten. 3. Dokumentation zur Anwendungsentwicklung organisieren und vereinheitlichen Alle Funktionen sollten eine einheitliche Anleitung zur Installation/Aktivierung der App, zur schnellen Einführung, zur Arbeit mit einer App nach der ersten Einführung und zur Bereitstellung der App enthalten. 4. Fügen Sie das Repository „electron-api-demos“ in die Dokumentation ein. Das Repository „elektron-api-demos“ enthält eine Reihe von Beispielen, die zeigen, wie Sie Ihrer Electron-Anwendung Funktionen hinzufügen. Diese Informationen sollten im Leitfaden zum Hinzufügen von Funktionen in Ihre App enthalten sein, um mit der Inhaltsstrategie der zentralen Informationsquelle übereinzustimmen. 5. Electron Fiddle-Beispiele in die Dokumentation einbinden Mit diesem Schritt können neue Entwickler leichter sehen, wie ein bestimmter Code funktioniert, ohne die Schritte manuell wiederholen zu müssen. Die Integration umfasst das Erstellen von Codebeispielen für die aktualisierten Anleitungen und das Hinzufügen der Schaltfläche „In Fiddle starten“ zu Codeblöcken.

TICKER

Überprüfungsphase der Bewerbung: Mach dich mit der Community und den Leuten vertraut, mit denen du zusammenarbeiten wirst. Hier findest du Leitfäden für Communitybeiträge und Best Practices. Erstellen Sie die ersten Beiträge. Bindung zu einer Community: Entdecke die Community. Prüfen Sie den aktuellen Status der Electron-Dokumentation. Schwachstellen identifizieren Woche 1 – Mit Mentoren über die Projektmeilensteine und -ergebnisse abstimmen Woche 2 – Seiten „Entwicklerumgebung“ und „Erste Electron-App schreiben“ überarbeiten Woche 3 – Seiten „Anwendungsarchitektur“, „App-Funktionen hinzufügen“, „App-Verpackung und -Verteilung“ überarbeiten Erstellen Sie eine Zusammenfassungsseite mit einer Liste der Funktionen, die der App hinzugefügt werden können. Wochen 4 – Restrukturieren Sie das Dokumentationsverzeichnis. Wochen 5 – Erstellen Sie eine Vorlage, wie electron-api-demos in die Hauptdokumentation eingebunden werden. Wochen 6–7 – Migrieren Sie das Repository „electron-api-demos“. Wochen 8 – Erstellen Sie eine Vorlage, wie Electron Fiddle in die Hauptdokumentation eingebunden wird. Schreiben Sie das erste Beispiel. 9. bis 10. Woche: Integration der Electron Fiddle in die Hauptdokumentation Woche 11: Abschluss der Hauptdokumentationsstruktur und -seiten nach der Migration des Repositorys "elektron-api-demos" und der Electron Fiddle-Beispiele Woche 12 – Ergebnisse auswerten

DETAILLIERTE AUFSCHLÜSSELUNG VON MEILENSTEINEN

ZEITRAUM FÜR DIE ÜBERPRÜFUNG DER ANMELDUNG Im ersten Teil des Zeitraums werden Community-Kanäle und Quellcode geprüft und Personen kontaktiert, die sich mit dem Projekt befassen.

Im zweiten Teil des Zeitraums wird die Kultur der Beiträge im Allgemeinen überprüft und es werden Leitfäden und Best Practices für Beiträge untersucht. Jetzt ist es an der Zeit, erste Beiträge zu erstellen, um zu sehen, wie der Ablauf funktioniert.

COMMUNITY-BONDING

Diesmal geht es um eine genauere Untersuchung des Dokumentenordners und seiner Roadmap. Anhand dieser Informationen lassen sich Schwachstellen (z.B. unvollständige oder fehlende Teile) erkennen, die verbessert werden können. Erstellen Sie (wenn möglich) Pull-Anfragen, um die Lücken zu füllen.

WOCHE 1 – WOCHE 2

Die erste Woche ist der Kommunikation mit Mentoren gewidmet, um sich auf die erwarteten Meilensteine und deren pünktliche Fertigstellung zu einigen.

In der zweiten Woche geht es um die Überarbeitung der Entwicklerumgebung und das Schreiben Ihrer First Electron App-Seiten. Für die Seite „Entwicklerumgebung“ umfasst dies das Überarbeiten der allgemeinen Übersicht und die Korrekturlesen. Für die Seite „Erste Electron-App schreiben“ bedeutet das, dass die Seite zu einem konsistenten, detaillierten Leitfaden mit klaren Anfangs- und Endpunkten werden soll. Außerdem werden redundante Informationen entfernt, z. B. zwei ähnliche Codeblöcke unter „Electron-Entwicklung in Kürze“ und „Dieses Beispiel ausprobieren“.

Lieferumfang: Überarbeitete, leicht verständliche Einführungsleitfäden für den Einstieg in Electron-Anwendungen.

WOCHE 3

Diese Woche geht es um: 1. Verbesserungen der Seite „Anwendungsarchitektur“. Dazu gehören: – Umformulierung der vorhandenen Informationen im Abschnitt „Haupt- und Renderer-Prozesse“, um sie für Erstleser einfacher und intuitiver zu gestalten – Hinzufügen einer visuellen Darstellung der Architektur, wie Prozesse verbunden sind, wie sie kommunizieren und wie sie sich grundlegend unterscheiden. Beispiele für Bildmaterial: Eins, zwei, drei (niedrige Qualität). 2. Einheitliche Informationen zu allen Funktionen, die Sie Ihrer Electron-Anwendung hinzufügen können. Dazu gehört auch, die Anleitungen so umzuformulieren, dass sie eine einheitliche Anleitung zum Installieren/Aktivieren einer Funktion sowie ein Beispiel zur Funktionsweise der Funktion enthalten. Außerdem wird eine neue Seite (Zusammenfassung) mit allen verfügbaren Funktionen erstellt. Die einheitliche Anleitung könnte so aussehen: – Übersicht – Beispiel: – Codebeispiel – Visuelles Beispiel (wenn möglich)

Vereinfachung der Seite für die Anwendungsverteilung. Dazu gehören: a. Zusammenführen des Artikels zum Anwendungs-Packaging in den Leitfaden zur Anwendungsbereitstellung b. Aufteilen der Bereitstellungsmethoden in automatisch und manuell c. Electron-Forge als Beispiel für die automatische Bereitstellung verwenden d. Informationen zu asar von der Seite zum Anwendungs-Packaging verwenden und das Kopieren von Quelldateien und das Erstellen eines asar-Archivs als Beispiele für die manuelle Bereitstellung beschreiben. #### WOCHE 4 In dieser Woche geht es darum, das Dokumentationsverzeichnis neu zu strukturieren. Dazu gehören:

1 – Die vorhandenen Anleitungen in mindestens drei Kategorien unterteilen: a. Kurzanleitung b. Grundlagen lernen c. Erweiterte Schritte

Die Kategorie „Kurzanleitung“ enthält die grundlegenden Anleitungen (Installation, Konfiguration, Distribution), um eine einheitliche Reihe von Leitfäden zu erstellen, mit denen Neueinsteiger den Schnellstart komplett neu erstellen können. Jeder Leitfaden sollte Links zu den vorherigen/nächsten Leitfäden in der Reihe enthalten.

Die Struktur kann so aussehen: 1. Voraussetzungen 2. Installieren Sie Electron. 3. Eine einfache Anwendung erstellen 4. Anwendung verpacken/verteilen

Nach Abschluss des Abschnitts „Schnellstart“ kennen die Nutzer die Grundlagen der Funktionsweise von Electron-Anwendungen und haben eine voll funktionsfähige, distribuierbare Electron-Anwendung.

Die Kategorie „Grundlagen lernen“ enthält die Leitfäden, mit denen Sie Ihr Wissen über Electron vertiefen und die in den Kurzanleitungsabschnitten erstellte Anwendung erweitern können. Dazu gehören: - Anwendungsarchitektur - Funktionen zu Ihrer App hinzufügen - Boilerplates und Befehlszeilen-Interfaces

Die Kategorie „Erweiterte Schritte“ enthält komplexere Leitfäden für die Konfiguration und Feinabstimmung Ihrer Electron-Anwendung: - Testen und Debuggen - Bedienungshilfen - Sicherheit - Updates

2: Die Anzahl der Dokumentationsseiten wird reduziert. Die aktuelle Version der Dokumentation enthält teilweise überlappende Inhalte und nicht kategorisierte Anleitungen. Beispiel: - Installation und Installation von Electron in der ersten App schreiben - App-Paketerstellung und App-Paketerstellung in einer Datei in der Application Distribution - Unkategorisierte Anweisungen in den Kategorien "Detaillierte Informationen" und "Erweitert": Empfehlung: Verschieben Sie die folgenden Dokumente nach GitHub und schließen Sie sie aus der Hauptdokumentation aus. Diese Dokumente beziehen sich speziell auf die Entwicklungsrichtlinien für Electron. Sie finden sie zuerst im Quellcode-Repository: - Developing Electron - Chromium Development - V8 Development - Issues in Electron - Patches in Electron - Pull Requests - Source Code Directory Structure - Testing - Coding Style

Die Hauptidee der Reduzierung besteht darin, eine unterdrückende Anzahl verfügbarer Leitfäden zu entfernen, die verstreut verstreuten Informationen zusammenzuführen und Neuankömmlingen eine strukturiertere, nutzerfreundlichere Version der Electron-Dokumentation zu bieten.

WOCHEN 5–7

In Woche 5 wird eine Vorlage für die Einbindung der Electron-API-Demos in die Hauptdokumentation erstellt. Diese Vorlage kann so aussehen: 1. Erstellen Sie in der Hauptdokumentation unter „Funktionen zu Ihrer App hinzufügen“ die Kategorien, die in den electron-api-demos vertreten sind. Wenn Sie die einzelnen Kategorien durchgehen, übertragen Sie die Demobeispiele in die Hauptdokumentation: – Codebeispiele können entweder aus dem Quellcode oder aus der Beschreibung der entsprechenden Funktion in der Anwendung entnommen werden – Auf jedes übertragene Beispiel muss die zugehörige Beschreibung folgen – Jedes untergeordnete Beispiel (z. B. Fehlerdialog als untergeordnetes Dialogfeld des Dialogfelds „System verwenden“) sollte im übergeordneten Dialogfeld übertragen werden

HINWEIS 1: Es gibt Beispiele, die sowohl in den Electron-API-Demos als auch in der Hauptdokumentation zu finden sind (z. B. Tastenkombinationen, Drag-and-drop). In diesem Fall sollte das Beispiel aus den electron-api-demos Vorrang haben und das Beispiel in der Hauptdokumentation ignoriert werden.

HINWEIS Nr. 2: Viele Beispiele in der Anwendung "elektron-api-demos" enthalten eine Live-Demo-Vorschau der beschriebenen Funktion oder Funktionalität. Diese Funktion wird bis zur Integration von Electron Fiddle in den Wochen 9 und 10 ignoriert.

Aktualisieren Sie die Seite mit allen verfügbaren Funktionen, die in Woche 3 erstellt wurden, und berücksichtigen Sie dabei die neue Hierarchie der Beispiele.

In Woche 6 und 7 werden die Beispiele für electron-api-demos gemäß der oben beschriebenen Vorlage in die Hauptdokumentation übertragen. Als letzten Schritt sollte das Repository „elektron-api-demos“ gelöscht oder verworfen werden.

WOCHEN 8–10

In Woche 8 bereiten Sie eine Vorlage vor, wie Electron Fiddle in die Hauptdokumentation eingebunden werden kann. Diese Initiative wurde bereits von Electron-Leuten und ehrenamtlichen Helfern aus der Region ins Leben gerufen (Details finden Sie in der Ausgabe Nr. 20442), aber sie erfordert eine ordnungsgemäße Durchführung.

Wenn Sie mit Fiddle-Beispielen fortfahren, könnte die grundlegende Vorlage so aussehen: 1. Wählen Sie ein Beispiel aus der Hauptdokumentation aus (z. B. den Schnellstart). Die Dokumentation sollte jetzt auch Beispiele für electron-api-demos enthalten. Erstellen Sie das Beispiel in Electron Fiddle neu (mit Beispielcode oder dem Quellcode als Ausgangspunkt). 3. Speichern Sie die Fiddle lokal in einem Ordner. 4. Verschieben Sie das Beispiel in /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * Die Liste der abgeschlossenen Beispiele wird im Abschnitt „Liste der Demos“ des Problems beschrieben. 5. Fügen Sie die Schaltfläche „In Fiddle starten“ hinzu, wie im ersten Kommentar zu Problem 2848 beschrieben.

In Woche 9 und 10 geht es darum, Beispiele für Elektron-API-Demos (die bereits in Fiddles umgewandelt wurden) gemäß der oben beschriebenen Vorlage in die Hauptdokumentation zu integrieren.

WOCHE 11

Diese Woche wird nach der erfolgreichen Migration des electron-api-demos-Repositories und der Electron Fiddle-Samples vollständig der Fertigstellung des Schreibprojekts gewidmet. Dazu gehört Folgendes: – Überprüfen, ob alle vorhandenen Codebeispiele die Schaltfläche „Launch in Fiddle“ enthalten – Überprüfen, ob alle vorhandenen Codebeispiele ordnungsgemäß als Fiddles funktionieren – Prüfen, ob die Hauptdokumentation nicht mehr auf das Repository „elektron-api-demos“ verweist

WOCHE 12

Abschluss der abgeschlossenen Arbeit. Akzeptanzprüfungen