moja global projekt

Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:
Moja weltweit
Technischer Redakteur:
Tlazypanda
Projektname:
Dokumentation zum technischen Onboarding-Leitfaden für FLINT
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

Dokumentation des technischen Onboarding-Leitfadens für FLINT, der neue Beitragende durch das technische Onboarding führt, damit neue Beitragende mit minimalem Support durch die Administratoren ganz einfach loslegen können.

Projektprobleme

Im Folgenden finden Sie eine Liste der wichtigsten Probleme im Zusammenhang mit der aktuellen Dokumentation: – Unübersichtliche Anleitungen im lokalen Einrichtungsleitfaden, die den Einstieg für neue Beitragende erschweren. – Mehrere Repositories von FLINT enthalten keine Dokumentation über ihren Zweck und sind nicht miteinander verknüpft, wodurch es für Einsteiger schwierig ist, zu erkennen, welches Repository installiert werden soll. - Windows-Installation ist gut dokumentiert, aber die Dokumentation zur Installation unter Linux bietet Verbesserungspotenzial. - Der Git-Workflow ist derzeit nicht Teil der Dokumentation.

Vorgeschlagene Lösung

Dieser Vorschlag bietet eine Lösung, um neue Beitragende durch ein technisches Onboarding zu führen, damit neue Beitragende mit minimalem Support durch die Administratoren ganz einfach loslegen können. Dies kann erreicht werden, indem die aktuelle Dokumentation so umgestaltet wird, dass sie für Einsteiger geeignet ist, und außerdem ein zentrales eigenständiges Repository für die gesamte verfügbare Dokumentation pflegen. Das Projekt ist in drei Phasen unterteilt: – – Vorhandene Dokumentation und Refaktorierung überprüfen: Das Ziel dieser Phase besteht darin, den aktuellen Leitfaden zu überprüfen und so umzugestalten, dass er prägnant und für neue Mitwirkende leicht verständlich ist. Außerdem muss die Dokumentation angepasst werden, um sie für Einsteiger zu optimieren, indem sie Badges, Emojis und Informationen zu Problemen enthält, die mit Tags für Personen, die nur für Erstanwender gedacht sind, oder als „Gut erste Probleme“ gekennzeichnet sind. - Erstellen eines zentralen, eigenständigen Dokumentations-Repositorys: Das Ziel dieser Phase besteht darin, die gesamte Dokumentation, die in einer logischen Reihenfolge für ein eigenständiges Repository verfügbar ist, zu verknüpfen. Dazu gehört die Bestellung der Beitragsrichtlinien, der Anweisungen zur Projekteinrichtung und der Schritt-für-Schritt-Anleitungen. - Entwickler-Workflow und Community-Website für neue Entwickler hinzufügen: Das Ziel dieser Phase besteht darin, den Entwickler-Workflow hinzuzufügen, der die Git-Beitragsrichtlinien und die technische Architektur des Projekts sowie die Test- und QA-Richtlinien enthält. Die vorgeschlagene Community-Website ist eine einseitige App, in der der Workflow, Probleme von Erstnutzern, auf die neue Beitragende Anspruch erheben können, und eine Liste aller Mitwirkenden angezeigt werden. Phase 1: Überprüfen der vorhandenen Dokumentation und Refaktorierung:

Ändern Sie die aktuelle Dokumentation der folgenden Repositories: – FLINT: Die aktuelle Dokumentation ist nicht sehr ausführlich und enthält keine sequenzielle Reihenfolge der erforderlichen Bibliotheken. Die Schritt-für-Schritt-Anleitungen sind in verschiedene PDFs unterteilt, können aber an zentraler Stelle zusammengefasst werden. Auch die Installationsanleitungen beziehen sich auf Fenster. Für die Linux-Installation kann die Weiterleitung zum Repository FLINT.docker jedoch von Vorteil sein. – FLINT.docker: Die aktuelle Dokumentation bietet nicht den Zweck der Festlegung dieses Repositorys, sondern darin, die Linux-Installation von FLINT über Docker bereitzustellen. Die Unterstützung durch Docker ist nur auf Ubuntu 18.04 (Bionic Beaver) beschränkt, kann aber auf andere Linux-basierte Distributionen ausgeweitet werden. In der aktuellen Dokumentation muss außerdem besonders auf die sequenzielle Einrichtung der Dockerfiles und auf genügend Informationen zum Erstellen aus dem Makefile geachtet werden. – FLINT.example: Die aktuelle Dokumentation bietet nicht den Zweck der Einrichtung dieses Repositorys, sondern ein Beispiel für die Verwendung von FLINT. Die verschiedenen Beispielausführungen lassen sich mit spezifischen Anweisungen für die Ausführung besser trennen. Wir müssen dieses Repository außerdem mit unserem FLINT-Haupt-Repository verknüpfen, damit Nutzer dieses Beispiel in Aktion sehen können.

Die folgenden Informationen müssen der aktuellen Dokumentation hinzugefügt werden: – Verwendung von Git und GitHub: Dies umfasst Schritt-für-Schritt-Anleitungen zum Fork, Klonen und anschließenden Einrichten des Remote-Upstreams für das Repository. Außerdem erhalten Sie Informationen dazu, wie Sie einen Rebasing auf Basis des neuesten Masters durchführen und Zusammenführungskonflikte lösen können. - Badges und Emojis: In der aktuellen Dokumentation fehlen Badges und Emojis. So fühlen sich neue Beitragende willkommen und finden Probleme weniger abschreckend. - Informationen zu Themen, die für Einsteiger bzw. für Einsteiger geeignet sind: Diese Angaben helfen dabei, neue Contributor auf anfängerfreundliche Themen und die Community-Website weiterzuleiten. - Informationen zum Importme-Repository: Das Importme-Repository dient als Basisvorlage für den Einstieg in ein Moja Global-Repository. In der aktuellen Dokumentation wird deren Bedeutung nicht erwähnt. Es muss aktualisiert werden, um das Importme-Repository zu erwähnen, und die Schritte zur Auswahl dieses Repositorys als Vorlage zum Erstellen eines neuen Repositorys müssen ebenfalls hinzugefügt werden. Darüber hinaus sollte es einen etablierten Prozess geben, in dem Programmierer zusätzliche Funktionen für das Importme-Repository vorschlagen.

Phase 2: Erstellen Sie ein zentrales, eigenständiges Dokumentations-Repository :

Für die Hostingplattform zu verwendendes Tool:

Die vorgeschlagenen Tools für diese Hostingplattform sind Read The Docs. Das hat folgende Gründe:- - Bei den verschiedenen Hostingplattformen wird das Tool sehr gut bewertet. – Automatische Aktualisierungen beim Senden von Commits – Da die große Community sie verwendet, ist die Einrichtung einfach und es gibt Unterstützung bei der Fehlerbehebung. – Die Dokumentation ist mit reStructuredText formatiert und die Ausgabe wird von Sphinx kompiliert.

Organisieren Sie alle Inhalte in einer logischen Reihenfolge:

Die vorgeschlagene Reihenfolge der Inhalte sieht so aus: – Einführung in die Entwicklerdokumentation: In diesem Abschnitt erhalten Sie eine Einführung in Moja Global und FLINT. – Beitragen: Dieser Abschnitt besteht aus den Unterabschnitten „Mögliche Beiträge“ (in Bezug auf Code/Berichterstellung für Fehler/Übersetzung/Dokumentation/Organisieren von Veranstaltungen usw.) und „Verhaltenskodex“. – Einrichtung des Entwicklungsteams: Dieser Abschnitt besteht aus den Unterabschnitten „Git- und GitHub-Workflow“, „Windows-Installation“, „Linux-Installation“. – Entwickler-Workflow: In diesem Abschnitt wird das Handbuch für integrierte Tools sowie weitere Tests und die Ausführung des Handbuchs für integrierte Tools erläutert. – Mach mit: Dieser Bereich bietet die verschiedenen Social-Foren wie Slack, um sich mit Moja Global auszutauschen und zusammenzuarbeiten.

Phase 3: Entwicklerworkflow und Community-Website für neue Beitragende hinzufügen:

Dokumentation zum Entwickler-Workflow:

Die Dokumentation zum Entwicklerworkflow umfasst die folgenden Unterabschnitte:

  • Verwendeter Technologie-Stack/Architektur und die verschiedenen Module im Code: Dokumentation, um die neuen Mitwirkenden mit dem implementierten Technologie-Stack, den verschiedenen Bibliotheken und Modulen der Codebasis vertraut zu machen.
  • Integrierte Test- und Abdeckungstools: Es wurden neue Mitwirkende zu den CI/CD-Pipelinetools für Tests, Abdeckungs-Bots und automatisierten Qualitätsprüfungen auf ihren Code hinzugefügt. Außerdem erhalten sie Richtlinien dazu, an wen sie sich wenden sollen, wenn die Tests nicht bestanden werden.
  • Bots, die den Workflow erleichtern, z. B. Zulipbot: Entwerfen von Inhaltsvorlagen für die Bots, die angezeigt werden sollen, und Bereitstellung von Dokumentation, damit Nutzer die Bots verstehen und sogar die Konfiguration des Bots durch Beiträge verbessern können.
  • Manuelles Testen und Einreichen einer Pull-Anfrage: Es soll eine Dokumentation zum manuellen Testen von Pull-Anfragen anhand bestimmter Standards und zum Hochladen der Ergebnisse in Form von Screenshots/GIFs beim Einreichen von Pull-Anfragen bereitgestellt werden.
  • Richtlinien für die Überprüfung von Pull-Anfragen, die von Beitragenden befolgt werden müssen: Richtlinien zum Taggen bestimmter Teams zur Überprüfung und zum Hinzufügen von Labels wie „Überprüfung erforderlich“ zur Pull-Anfrage, damit die Administratoren antworten können.
Community-Website:

Die Community-Website bietet folgende Funktionen:

  • Informationen zu unserem Workflow: Der Workflow umfasst eine Reihe von Aktionen, mit denen ein neuer Beitragender beginnen kann: Beanspruchen eines Problems beim ersten Timer, gefolgt von dem Erstellen eines Problems mit ersten Timern für einen anderen Nutzer und um anderen Nutzern zu helfen, indem sie Feedback geben und deren Pull-Anfragen überprüfen.
  • Liste der Probleme, die nur für erstmalige Timer vorgesehen sind: Die Liste mit Problemen, die speziell für Neueinsteiger oder neue Beitragende gedacht sind.
  • Liste veralteter Probleme: Eine Liste von Problemen, an denen seit langer Zeit nicht mehr gearbeitet wurde und die daher von Beitragenden ausgewählt werden können.
  • Liste der Beitragenden: Die Liste der Beitragenden, die bisher zu Moja Global-Repositories beigetragen haben.
  • Letzte Beitragende: Die Liste der Beitragenden, die kürzlich Beiträge zu Moja Global-Repositories geleistet haben.
  • Links zum Beitritt zu Chatforen: Informationen und Links zum Beitritt zur Slack-Community, um Fragen zu klären und weitere Projekte zu diskutieren.