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:
- gRPC-Gateway
- Technischer Redakteur:
- Iramajiv
- Projektname:
- Refactoring der vorhandenen Docs-Website von gRPC-Gateway
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
ZUSAMMENFASSUNG:
Die Website mit den Nutzerdokumenten soll Endnutzern bei der Verwendung eines Produkts oder Dienstes helfen. Die Website mit den guten Nutzerdokumenten ist sehr wichtig, da sie Nutzern die Möglichkeit bietet, die Software, ihre Funktionen, Tipps und Tricks kennenzulernen und häufige Probleme bei der Verwendung der Software zu beheben. Es senkt auch die Supportkosten und ist Teil der Corporate Identity des Produkts. Eine gute Nutzerdokumentationswebsite ist ein Zeichen dafür, dass das Produkt, das Entwicklerteam, intakt ist. Ohne eine gute Website mit Nutzerdokumenten weiß ein Nutzer möglicherweise nicht, wie er die oben genannten Dinge effektiv und effizient erledigen kann. Die Website mit den Nutzerdokumenten kann eine entscheidende Rolle für den Erfolg eines Produkts spielen, da eine gute Kommunikation immer im Mittelpunkt eines Unternehmens oder Produkts steht und eine gute Dokumentation diese Kommunikation in ein überschaubares Rahmenwerk stellt, auf das alle zugreifen können, um erfolgreich zu sein.
Zum Zeitpunkt der Erstellung dieses Artikels wurde das gRPC-Gateway-Repository ungefähr 1.200 Mal geforkt und 184 Personen haben zu diesem Repository beigetragen. Das zeigt, dass viele Menschen auf der ganzen Welt das gRPC-Gateway verwenden und sich möglicherweise die Nutzerdokumentation zur Verwendung des gRPC-Gateways ansehen möchten. Die gRPC-Gateway-Nutzerdokumentation und die Dokumentationswebsite sind jedoch derzeit veraltet und unvollständig. Die gRPC-Gateway-Community möchte mit diesem Projekt die vorhandene Dokumentationswebsite überarbeiten und verbessern, damit Endnutzer das gRPC-Gateway nahtlos nutzen können.
AKTUELLER STATUS:
Derzeit gibt es auf der Website mit gRPC-Gateway-Dokumenten zwei Hauptprobleme:
• Das erste Problem ist die schlechte und veraltete Website mit Dokumenten. Das Design und die Struktur der Website und das verwendete Design sind veraltet, unvollständig, schwer zu bedienen oder Informationen zu finden und deckt nicht viele Funktionen einer guten Website mit Dokumenten ab. Die Umstrukturierung der vorhandenen Docs-Website von gRPC-Gateway umfasst das Design der Website, das Hinzufügen von Funktionen wie der Dokumentsuche, die Verbesserung der Benutzeroberfläche der Website, die Organisation von Anleitungen und Beispielen in einer geeigneten Seitenleiste und die Aktualisierung der vorhandenen Flussdiagramme und Bilder durch das Entwerfen neuer. Dies wird mein Hauptziel sein und meine Arbeit wird sich hauptsächlich auf das Design und die Neustrukturierung der vorhandenen Docs-Website konzentrieren.
• Das zweite Problem besteht darin, dass die vorhandene Dokumentation, Anleitungen und Beispiele usw. für gRPC-Gateway überarbeitet werden müssen. Dazu müssen typografische und grammatische Fehler in den Dateien behoben, Go-Snippets richtig ausgerichtet und Go-Snippets gemäß Gofmt-Formaten umstrukturiert werden. Falls ja, können wir bei Bedarf weitere Dokumentationen, Anleitungen und Beispiele hinzufügen oder die vorhandenen Dateien nach dem Refactoring wiederverwenden. Dies ist mein sekundäres Ziel und ich werde es angehen, nachdem ich mein primäres Ziel erreicht habe, d.h. das Design und die Struktur der vorhandenen Docs-Website überarbeitet habe.
WARUM IST MEINE VORGESCHLAGENE DOCS-WEBSITE EINE VERBESSERUNG GEGENÜBER DER AKTUELLEN?
Die vorgeschlagene Website für Nutzerdokumente soll die Effizienz, Konsistenz und Sicherheit für Endnutzer verbessern und gewährleisten. Die Website sieht dann ansprechender aus und die Benutzeroberfläche ist mit gut gestalteten Abschnitten und Funktionen mit schriftlichen Anleitungen und zugehörigen Flussdiagrammen und Bildern ausgestattet.
Die gRPC-Gateway-Dokumentation enthält eine gute Beschreibung der Methode und des Beispiels. Es wird jedoch immer noch das alte Jekyll-Design verwendet. Heutzutage gibt es jedoch bessere Jekyll-Designs für SSGs (Static Site Generators). Außerdem müssen die Seiten neu strukturiert und für Nutzer nützlicher gemacht werden, indem neue Beispiele und Anleitungen hinzugefügt und die bisherigen Inhalte aktualisiert und umgeschrieben werden.
STRUKTUR UND ROADMAP DER VORGESCHLAGENEN ZIELE UND IDEEN:
PRIMÄRES ZIEL DIESES PROJEKTS:-
Die oben genannten Ziele und Ideen können auf folgende Weise umgesetzt werden:
Das aktuelle Jekyll-Design wird durch ein besseres und stabileres Design ersetzt. Der Grund für die erneute Verwendung von Jekyll-Themes ist, dass es für die Entwickler einfach ist, Beiträge zu leisten und den Workflow des Projekts zu verstehen, da sie bereits mit dem vorhandenen Jekyll-Framework und dem Jekyll-Design vertraut sind, das dem neuen Jekyll-Design ähnelt.
Nachdem ich verschiedene Jekyll-Themes im Internet durchgegangen bin, fand ich diese https://idratherbewriting.com/documentation-theme-jekyll/ Themes-Suite aufgrund der folgenden Funktion am besten für die gRPC-Gateway-Dokumentationswebsite:
• Markdown: Damit sich technische Redakteure nicht um die Installation kümmern müssen. Sie können einfach in die .md-Datei schreiben. Jeder kann auf die Schaltfläche „Bearbeiten“ auf der Website klicken (neue Funktion) und Beiträge leisten (Seite in GitHub bearbeiten/Änderungen vorschlagen), um sie zu verbessern. So werden Nutzer dazu angeregt, neue Inhalte hinzuzufügen oder vorhandene Inhalte zu bearbeiten, um sie zu verbessern.
• Suche in der Dokumentation: Nutzer sollten ein Suchfeld haben, damit sie relevante Inhalte schnell und einfach finden können.
• Kommentarbereich: – Der Nutzer kann möglicherweise Beiträge und Anleitungen kommentieren und seine Meinung teilen. Sie können die Ansichten anderer Personen zur Projektdokumentation lesen.
• Neue Versionshinweise und Blogs: Die Website sollte mit neuen Blogposts und Neuigkeiten zur aktuellen Entwicklung und Roadmap aktualisiert werden. Daher sollte auf der Landingpage eine Art Blog vorhanden sein.
• Schnelle Entwicklung: Die meisten SSG-Frameworks (Static Site Generator) werden auf dem Server ausgeführt und Änderungen an der Datei werden sofort in der Benutzeroberfläche übernommen. Außerdem sollte der Bereitstellungs- und Build-Prozess einfach sein. Künftig verwenden wir das Framework, wenn wir das Framework ändern möchten. Dann sollte es einfach sein. Die meisten Frameworks unterstützen die Markdown-Schreibweise. Es sollten also nur die .md-Dateien verschoben und einige Änderungen vorgenommen werden müssen.
Hier unterteile ich die vorhandenen Websiteseiten in neue Websitebereiche und -seiten :
• Landingpage:-
Auf der Landingpage sollten die wichtigsten Funktionen des gRPC-Gateways hervorgehoben werden.
- Erste Schritte mit gRPC-Gateway (Weiterleitung zum Leitfaden)
- Einfache Installationsanleitung (kurze Befehle)
- Vorteile von gRPC-Gateway
- Projekt mit gRPC-Gateway
Anstatt eine lange Beschreibung zu verfassen, sollten Sie also die wichtigsten Punkte auf der Landingpage präsentieren und einen Link zu den Details angeben.
• Seite mit der gRPC-Gateway-Anleitung:
- Installationsanleitung
- Schneller Einstieg in gRPC-Gateway
• Entwicklerleitfaden für gRPC-Gateway:
Der Entwicklungsleitfaden, der Leitfaden für Beiträge, die Git-Einrichtung, der Verhaltenskodex, die Dokumentationseinrichtung, der Entwicklungsablauf usw. verweisen auf ähnliche Seiten im Inneren. Daher müssen alle Dateien umstrukturiert und neu angeordnet werden. Die Hauptentwicklungsseite sollte alle diese Seiten enthalten und in jedem Schritt wird der Hyperlink erstellt.
• Seite „About gRPC-Gateway“:
In den Teambereichen sollte eine Liste aller Mitwirkenden vorhanden sein. Schnellinfos und Releasenotes sowie die neuesten Blogbeiträge werden hinzugefügt, um die Nutzer dazu anzuregen, sich über die aktuellen gRPC-Gateway-Neuigkeiten zu informieren.
• Seite mit Blogs, Versionshinweisen und Anleitungen:
Ich finde, dass die Website eine Blogging-Option haben sollte. So können Neuigkeiten und Pressemitteilungen ganz einfach kommuniziert werden. Die Seite mit der Anleitung enthält einige beliebte Vorträge und Artikel, in denen gRPC-Gateway APIs und -Konzepte erläutert werden. Beitragende können ihre Anleitungslinks auf der Anleitungsseite hinzufügen.
Nachdem Sie die oben beschriebene Aufgabe abgeschlossen haben, nehmen Sie dieselben Änderungen am V2-Zweig vor und gleichen Sie ihn mit dem Master-Zweig des gRPC-Gateways ab.
SEKUNDÄRES ZIEL DIESES PROJEKT:-
Weitere Änderungen sind erforderlich, um die gRPC-Gateway-Dokumentation robuster und leserlicher zu machen:
• Korrektur von Grammatik- und Tippfehlern sowie Organisation und Ausrichtung von Links und Beiträgen auf der Website in allen vorhandenen Dateien des gRPC-Gateways.
• Bei Bedarf weitere Dokumentation und Inhalte in gRPC-Gateway hinzufügen, da die meisten Funktionen nur sehr kurz dokumentiert sind, z. B. im Abschnitt „Dokumentation“ der Website zu AWS, Hintergrund und Verwendung usw.
• Refaktorierung von Go Snippets des gRPC-Gateways entsprechend den Gofmt-Formaten
Nachdem Sie die oben beschriebene Aufgabe abgeschlossen haben, nehmen Sie dieselben Änderungen am V2-Zweig vor und gleichen Sie ihn mit dem Master-Zweig des gRPC-Gateways ab.
WARUM BIN ICH DIE RICHTIGE PERSON FÜR DIESES PROJEKT:
Ich glaube, dass ich die richtige Person für dieses Projekt bin, weil:
• Ich habe bereits Erfahrung mit der Verbesserung der Dokumentation von Organisationen und kann jedes Versionskontrollsystem verwenden. Daher ist die Ausführung von Befehlen auf GitHub kein Problem für mich. • Was mich außerdem antreibt, ist die Arbeit an Projekten, die Mehrwert für die Menschen schaffen. Ich glaube, wenn man möchte, dass jemand etwas auf die effizienteste Weise tut, muss man dies dokumentieren. Wenn Sie Ihre Prozesse dokumentieren, sorgen Sie für Effizienz, Konsistenz und Sicherheit für alle Beteiligten. • Ich bin mit dem Workflow und der Codebasis von gRPC-Gateway vertraut, da ich seit zwei Monaten zu gRPC-Gateway beitrage und 11 PRs zusammengeführt wurden.