Diese Seite wurde von der Cloud Translation API übersetzt.

Elektronenprojekt

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:: Elektro
Technischer Redakteur:: Mister Gold
Projektname:: Anleitung für Elektronen
Projektdauer:: Standarddauer (3 Monate)

Projektbeschreibung

PROJEKTZUSAMMENFASSUNG

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

Die Beliebtheit von Electron liegt in seiner einfachen Lernkurve und der niedrigen Eingabeschwelle – jeder, der JavaScript-, HTML- und CSS-Stack kennt, kann seine eigene Anwendung erstellen. Aufgrund der hohen Gesamtwachstumsrate müssen Anleitungen und Startleitfäden erstellt werden, die leicht verständlich sind.

Ziel des Projekts ist es, Anwendungsentwicklern, die neu mit dem Electron-Framework sind, Vertrauen zu gewinnen und ihnen eine einheitliche und optimierte Erfahrung bei der Entwicklung ihrer eigenen Electron-Anwendungen von Grund auf zu bieten.

Projektprobleme

Im Folgenden finden Sie eine Liste der wichtigsten Themen im Zusammenhang mit der Dokumentation zu Elektron-Anleitungen: 1. Unklarer Ausgangspunkt und nicht intuitive Informationen zu den Schritten der Anwendungsentwicklung 2. Gestreute und redundante Informationen im Zusammenhang mit dem Anwendungsentwicklungsprozess. 3. Unorganisierte Anleitungen im Startleitfaden ohne Single Source of Truth

PROPOSAL

Je nach Projektziel und den oben beschriebenen Problemen finden Sie hier eine Liste der vorgeschlagenen Verbesserungen: 1. Aktualisieren Sie die vorhandenen Führungslinien. Damit die ersten Schritte reibungslos und einheitlich sind, sollten die folgenden Dokumente mit einer schrittweisen Umstellung von einfach zu komplexer aktualisiert werden: – Entwicklungsumgebung – Ihre erste Elektron-Anwendung schreiben – Funktionen zu Ihrer Anwendung hinzufügen (Zusammenfassungsseite erstellen) – Paketerstellung und -verteilung der Anwendung 2. Sie strukturieren das Dokumentationsverzeichnis neu. Um neuen Entwicklern zu zeigen, was für die ersten Schritte wichtig ist und was als weitere Schritte betrachtet werden kann, sollte die Seite „Dokumente“ eine visuelle und kontextbezogene Aufteilung der Schritte enthalten, damit die erste Anwendung so schnell wie möglich live geschaltet wird. Die Restrukturierung umfasst auch Hinweise zu den möglichen nächsten Schritten. 3. Dokumentation zur Anwendungsentwicklung organisieren und vereinheitlichen Für alle Funktionen sollte eine einheitliche Anleitung zur Installation/Aktivierung, zu den schnellen ersten Schritten, zur Arbeit mit einer App nach der ersten Veröffentlichung und zur Bereitstellung der App vorhanden sein. 4. Fügen Sie das Repository „elektroron-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 zu Ihrer App enthalten sein, damit sie im Einklang mit einer Single Source of Truth-Inhaltsstrategie stehen. 5. Elektron-Fiddle-Beispiele in die Dokumentation einbinden So können neue Entwickler leichter sehen, wie ein bestimmter Code funktioniert, ohne die Schritte manuell wiederholen zu müssen. Die Integration umfasst das Schreiben von Codebeispielen für die aktualisierten Anleitungen und das Hinzufügen der Schaltfläche „In Fiddle starten“ zu Codeblöcken.

TICKER

Überprüfungszeitraum der Bewerbung: Machen Sie sich mit der Community und den Personen, mit denen Sie zusammenarbeiten können, vertraut. Hier findest du Leitfäden und Best Practices für Beiträge aus der Community. Erstelle die ersten Beiträge. Verbundenheit mit der Gemeinschaft: Erkunde die Community. Prüfen Sie den aktuellen Status der Electron-Dokumentation. Schwachstellen identifizieren Woche 1: Sich mit den Mentoren über Projektmeilensteine und -ergebnisse abstimmen Woche 2 – Entwicklerumgebung überarbeiten und Seiten für die erste Electron-Anwendung schreiben Woche 3 – Anwendungsarchitektur überarbeiten, Funktionen zu Ihrer App hinzufügen, App-Paketerstellung und Seiten zum Vertrieb. Übersichtsseite mit einer Liste der Funktionen erstellen, die der App hinzugefügt werden können Woche 4 – Dokumentationsverzeichnis neu strukturieren Woche 5 – Vorlage zur Integration von Electron-API-Demos in die Hauptdokumentation vorbereiten Woche 6 bis 7 – Repository „elektron-api-demos“ migrieren Woche 8 – Vorlage zur Integration von „Electron Fiddle“ in die Hauptdokumentation vorbereiten Schreiben Sie die erste Stichprobe. Woche 9–10: Elektron-Fiddle in die Hauptdokumentation einbinden Woche 11 – Struktur der Hauptdokumentation und Seiten nach der Migration des „elektron-api-demos“-Repositorys und der Elektron-Fiddle-Beispiele fertigstellen Woche 12 – Ergebnisse auswerten

DETAILLIERTE AUFNAHME DER MEILENSTEINE

ÜBERPRÜFUNGSZEIT DES BEWERBUNGSZEITRAUMS Im ersten Teil des Zeitraums werden die Community-Kanäle und der Quellcode geprüft und Personen kontaktiert, die sich dem Projekt widmen.

Im zweiten Teil des Zeitraums widmen wir uns der allgemeinen Überprüfung der Beitragskultur sowie der Beitragsleitfäden und Best Practices. Dies ist der Zeitpunkt der ersten Beiträge, um zu sehen, wie der Ablauf funktioniert.

COMMUNITY-VERBINDUNG

In dieser Zeit wird der Dokumentationsordner und seine Roadmap eingehender untersucht. Anhand dieser Informationen lassen sich Schwachstellen (z.B. unvollständige oder fehlende Teile) identifizieren, die verbessert werden können. Erstellen Sie nach Möglichkeit Pull-Anfragen, um die Lücken zu füllen.

WOCHE 1 - WOCHE 2

Die erste Woche wird der Kommunikation mit den beratenden Personen gewidmet, um die erwarteten Meilensteine und deren pünktliche Lieferung zu besprechen.

In der zweiten Woche geht es um die Überarbeitung der Entwicklungsumgebung und das Schreiben Ihrer ersten Elektron-App-Seiten. Für die Seite „Entwicklerumgebung“ umfasst sie die Umformulierung des allgemeinen Überblicks und das Korrekturlesen. Auf der Seite Writing Your First Electron App wird die Seite als einheitliche Schritt-für-Schritt-Anleitung mit klaren Start- und Endpunkten gestaltet. Dabei werden redundante Informationen entfernt, z. B. zwei ähnliche Codeblöcke unter „Elektronentwicklung in einer Nutshell“ und „Testen dieses Beispiels“.

Ergebnisse: Überarbeitete, leicht verständliche Einführungsleitfäden zum Schnellstart mit Electron-Anwendungen.

WOCHE 3

Diese Woche beschäftigen wir uns mit: 1. Verbesserungen der Seite "Anwendungsarchitektur". Dazu gehört Folgendes: – Umformulierung der vorhandenen Informationen in den Abschnitten zu den Haupt- und Renderer-Prozessen, um diese für Einsteiger einfacher und intuitiver zu gestalten – Hinzufügen einer visuellen Darstellung der Architektur, der Verknüpfung von Prozessen, der Kommunikation zwischen ihnen und ihren wesentlichen Unterschieden. Beispiele für Bilder: Eins, zwei, drei (niedrige Qualität). 2. Zusammenführung von Informationen über alle Funktionen, die Sie der Electron-Anwendung hinzufügen können Dazu gehört auch, die Leitfäden so umzuformulieren, dass sie einheitliche Anleitungen zum Installieren/Aktivieren einer Funktion sowie ein Beispiel für die Funktionsweise der Funktion enthalten. Außerdem wird eine neue Seite (Zusammenfassung) erstellt, auf der alle verfügbaren Funktionen aufgeführt sind. Die einheitliche Anleitung kann so aussehen: – Übersicht – Beispiel: – Codebeispiel – Visuelles Beispiel (wenn möglich)

zur Vereinfachung der Seite für die Anwendungsbereitstellung. Dazu gehört Folgendes: a. Zusammenführen von Application Packaging mit dem Leitfaden zur Anwendungsverteilung b. Unterteilen von Verteilungsmethoden in automatische und manuelle c. Elektronenschmiede als Beispiel für die automatische Verteilung d. Aufnahme von Informationen zu asar von der Seite zum Erstellen von Anwendungen, das Kopieren von Quelldateien und das Erstellen eines Asar-Archivs als Beispiele für die manuelle Verteilung. #### WOCHE 4 In dieser Woche geht es um die Umstrukturierung des Dokumentationsverzeichnisses. Er enthält:

1. Die vorhandenen Führungslinien werden in mindestens drei Kategorien aufgeteilt: a. Kurzanleitung b. Grundlagenkenntnisse c. Erweiterte Schritte

Die Kategorie „Schnellstart“ enthält grundlegende Anleitungen (Installation, Konfiguration, Verteilung), die eine konsistente Reihe von Leitfäden erstellen, mit denen Neueinsteiger einen Schnellstart von Grund auf beginnen können. Jeder Leitfaden sollte Links zu vorherigen/nächsten Leitfäden der Reihe enthalten.

Die Struktur könnte so aussehen: 1. Voraussetzungen 2. Installieren Sie Electron. 3. Einfache Anwendung erstellen 4. Anwendung verpacken/verteilen

Nach Abschluss des Abschnitts mit der Kurzanleitung kennt der Nutzer die Grundlagen der Funktionsweise von Electron-Anwendungen und hat eine voll funktionsfähige, verteilbare Electron-Anwendung.

Die Kategorie "Grundlagen lernen" enthält die Leitfäden, die dazu dienen, das Wissen über Electron zu vertiefen und die in den Schnellstart-Abschnitten erstellte Anwendung zu erweitern. Zu diesen Leitfäden gehören: – Anwendungsarchitektur – Funktionen zu Ihrer Anwendung hinzufügen – Textbausteine und Kommandozeilen

Die Kategorie „Erweiterte Schritte“ enthält weiterführende Leitfäden zur Konfiguration und Feinabstimmung der Electron-Anwendung: – Tests und Fehlerbehebungen – Bedienungshilfen – Sicherheit – Updates

2: Die Anzahl der Dokumentationsseiten wird reduziert. Die aktuelle Version der Dokumentation enthält einen gewissen Grad an überlappenden Inhalten und nicht kategorisierten Anleitungen. Beispiel: – Installation und Installation von Electron innerhalb der ersten Anwendung – Paketerstellung der Anwendung und Packen der Anwendung in eine Datei innerhalb der Anwendungsbereitstellung – Nicht kategorisierte Anweisungen in den Kategorien „Im Detail“ und „Erweitert“: Vorschlag: Verschieben Sie die folgenden Dokumente in GitHub und schließen Sie sie aus der Hauptdokumentation aus. Diese Dokumente beziehen sich speziell auf die Richtlinien für die Electron-Entwicklung und Sie suchen zuerst im Quell-Repository: - Elektron entwickeln - Chromium-Entwicklung - V8-Entwicklung - Probleme in Elektron - Patches in Electron - Pull-Anfragen - Struktur des Quellcode-Verzeichnisses - Tests - Programmierstil

Die Hauptidee der Reduktion besteht darin, eine bedrückende Anzahl verfügbarer Anleitungen zu entfernen, die verstreuten Puzzleteile zusammenzuführen und Neulingen eine strukturiertere, nutzerfreundlichere und nutzerfreundlichere Version der Electron-Dokumentation zu bieten.

WOCHEN 5–7

In Woche 5 geht es darum, eine Vorlage (eine Möglichkeit) für die Integration von Elektronen-API-Demos in die Hauptdokumentation zu erstellen. Diese Vorlage könnte so aussehen: 1. Erstellen Sie in der Hauptdokumentation unter „Hinzufügen von Features zu Ihrer Anwendung“ die Kategorien, die in der Datei „elektron-api-demos“ dargestellt werden. 2. Gehen Sie die einzelnen Kategorien durch und ü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 sollte die zugehörige Beschreibung folgen – Jedes untergeordnete Beispiel (z. B. ein Fehlerdialog als untergeordnetes Element des Dialogfelds „System verwenden“) sollte unter dem jeweils übergeordneten Dialogfeld übertragen werden.

HINWEIS Nr. 1: Es gibt Beispiele, die sowohl in Electron-API-Demos als auch in der Hauptdokumentation vorhanden sind (z. B. Tastenkombinationen, Drag & Drop). In diesem Fall sollte das Beispiel aus den „elektron-api-demos“ die Priorität erhalten und das Beispiel in der Hauptdokumentation ignoriert werden.

HINWEIS Nr. 2: Viele Beispiele in der Anwendung „elektron-api-demos“ bieten eine Live-Demo-Vorschau der beschriebenen Funktion. Diese Funktion wird bis zur Einbindung der Electron Fiddle in den Woche 9–10 ignoriert.

Aktualisieren Sie die Seite mit allen verfügbaren Funktionen, die in Woche 3 erstellt wurden, unter Berücksichtigung der neuen Hierarchie der Beispiele.

In den Wochen 6 und 7 werden die Elektronen-API-Demos-Beispiele 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 wird eine Vorlage (eine Möglichkeit) für die Integration von Electron Fiddle in die Hauptdokumentation erstellt. Diese Initiative wurde bereits von Electron-Experten und Freiwilligen aus der Community gestartet (Details finden Sie unter Ausgabe Nr. 20442). Sie muss jedoch richtig abgeschlossen werden.

Um mit Fiddle-Beispielen fortzufahren, kann die Basisvorlage so aussehen: 1. Wählen Sie ein Beispiel aus der Hauptdokumentation aus, z. B. die Kurzanleitung. An dieser Stelle sollte die Dokumentation auch Elektronen-API-Demos-Beispiele enthalten. 2. 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 fertigen Beispiele finden Sie im Abschnitt „Liste der Demos“ für das Problem. 5. Fügen Sie die Schaltfläche „In Fiddle starten“ hinzu, wie im ersten Kommentar unter Problem Nr. 2848 beschrieben.

In den Wochen 9 und 10 werden Elektronen-API-Demos, die bereits in Fiddles umgewandelt wurden, gemäß der oben beschriebenen Vorlage in die Hauptdokumentation integriert.

WOCHE 11

In dieser Woche widmen wir uns dem Abschluss des Schreibprojekts nach erfolgreicher Migration des Repositorys „elektron-api-demos“ und der Elektron Fiddle-Beispiele. Dies umfasst Folgendes: – Prüfen, ob alle vorhandenen Codebeispiele die Schaltfläche „In Fiddle starten“ haben – Prüfen, ob alle vorhandenen Codebeispiele als Fiddles funktionieren – Prüfen, ob sich die Hauptdokumentation nicht mehr auf das Repository „Electron-api-demos“ bezieht

WOCHE 12

Abschluss abgeschlossener Arbeiten. Akzeptanzprüfungen.