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:
- gRPC-Gateway
- Technischer Redakteur:
- iamrajiv
- Projektname:
- Vorhandene Docs-Website des gRPC-Gateways refaktorieren
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
ZUSAMMENFASSUNG:
Die User Docs-Website soll Endnutzer bei der Verwendung eines Produkts oder einer Dienstleistung unterstützen. Eine gute Website für Nutzerdokumente ist sehr wichtig, da sie Nutzern die Möglichkeit bietet, die Verwendung der Software zu erlernen, ihre Funktionen zu verwenden, Tipps und Tricks zu erhalten und häufig auftretende Probleme zu lösen, die bei der Verwendung der Software auftreten. Es reduziert auch die Supportkosten und ist Teil der Unternehmensidentität des Produkts. Die gute Dokumentationswebsite ist ein Zeichen für die Integrität des Produkts – das Entwicklerteam. Ohne eine gute Website für Nutzerdokumente wissen die Nutzer möglicherweise nicht, wie sie die oben genannten Schritte effektiv und effizient erledigen können. Die User Docs-Website kann eine entscheidende Rolle für den Erfolg eines Produkts spielen, da gute Kommunikation im Mittelpunkt jedes Unternehmens oder Produkts steht und bleibt. Eine gute Dokumentation fügt sie einfach in ein überschaubares Framework ein, auf das jeder Zugriff hat, um erfolgreich zu sein.
Zum Zeitpunkt der Veröffentlichung dieses Dokuments wurde das gRPC-Gateway-Repository ungefähr 1200 Mal abgezweigt und 184 Personen haben zu diesem Repository beigetragen. Dies zeigt, dass viele Menschen auf der ganzen Welt das gRPC-Gateway verwenden und möglicherweise die Benutzerdokumentation für Anleitungen zur Verwendung des gRPC-Gateways lesen möchten. Allerdings sind die Benutzerdokumentation und die Docs-Website des gRPC-Gateways derzeit veraltet und unvollständig und die gRPC-Gateway-Community möchte dieses Projekt zur Refaktorierung der vorhandenen Docs-Website verwenden, um ihre Dokumentationswebsite zu verbessern, um Endnutzern eine nahtlose Erfahrung bei der Verwendung des gRPC-Gateways zu ermöglichen.
AKTUELLER STATUS:
Derzeit hat die Website der gRPC-Gateway-Dokumentation zwei größere Probleme:
• Das erste Problem ist eine schlechte und veraltete Text & Tabellen-Website, da der Stil und die Struktur der Website und des verwendeten Designs veraltet, unvollständig, schwer zu navigieren oder Informationen sind und viele Funktionen einer guten Google Text & Tabellen-Website nicht abgedeckt sind. Die Refaktorierung der vorhandenen Docs-Website des gRPC-Gateways umfasst den Stil der Website, das Hinzufügen von Funktionen wie die Dokumentsuche usw., die Verbesserung der Benutzeroberfläche der Website, das Organisieren von Anleitungen und Beispielen in einer geeigneten Seitenleiste und die Aktualisierung der vorhandenen Flussdiagramme und Bilder durch das Entwerfen eines neuen Flussdiagramms usw. Dies wird mein primäres Ziel sein und meine Arbeit wird mehr auf dem Stil und der Neustrukturierung vorhandener Google Docs-Websites basieren.
• Das zweite Problem besteht darin, dass die vorhandene Dokumentation, Anleitungen, Beispiele usw. des gRPC-Gateways refaktoriert werden müssen. Dies kann durch das Entfernen von typografischen und grammatikalischen Fehlern in den Dateien, eine ordnungsgemäße Ausrichtung der Go-Snippets und eine Refaktorierung von Go-Snippets gemäß den Gofmt-Formaten erfolgen. Wenn ja, können wir bei Bedarf weitere Dokumentationen, Anleitungen und Beispiele hinzufügen oder die vorhandenen Dateien nach der Refaktorierung wiederverwenden. Das ist mein sekundäres Ziel und ich werde es tun, nachdem ich mein primäres Ziel erreicht habe, nämlich das Gestalten und Neustrukturieren einer vorhandenen Google Docs-Website.
WARUM IST MEIN VORGESCHLAGENE DOKUMENT-WEBSITE EINE VERBESSERUNG ÜBER DIE AKTUELLE?
Die vorgeschlagene Website für Nutzerdokumente ist so strukturiert, dass sie Effizienz, Einheitlichkeit und ein sicheres Gefühl für den Endnutzer gewährleistet. Es wird das Aussehen verbessern und die Benutzeroberfläche mit gut stilisierten Abschnitten und Funktionen verbessern, die schriftliche Leitfäden sowie die zugehörigen Flussdiagramme und Bilder enthalten.
Die Dokumentation zu gRPC-Gateway bietet eine gute Beschreibung der Methode und das Beispiel. Es wird jedoch immer noch das alte Jekyll-Design verwendet und auch heute bieten wir bessere Jekyll-Designs für die SSG (Static Site Generator). Außerdem müssen Seiten neu strukturiert und für Nutzer nützlicher gestaltet werden, indem neue Beispiele und Anleitungen hinzugefügt und die vorherigen Inhalte aktualisiert und umgeschrieben werden.
STRUKTUR UND PLANUNG 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 auf ein besseres und robustes Design umgestellt. Der Grund für die erneute Verwendung von Jekyll-Themen ist, dass es für die Pflegekräfte einfach sein wird, einen Beitrag zu leisten und den Workflow des Projekts zu verstehen, da sie bereits das vorhandene Jekyll-Framework und -Design kennen, das dem neuen Jekyll-Design ähnelt.
Nachdem ich verschiedene Jekyll-Themen 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-Dokumentations-Website:
• Markdown: So müssen sich technische Redakteure nicht um die Installation kümmern. Sie können einfach in die MD-Datei schreiben. Jeder kann auf die Schaltfläche „Bearbeiten“ auf der Website klicken (neue Funktion) und einen Beitrag erstellen (bearbeiten/Änderungen für die Seite in GitHub vorschlagen), um die Seite zu verbessern. Dadurch können Nutzer neue Inhalte hinzufügen oder Inhalte bearbeiten, um sie zu verbessern.
• Dokumentationssuche: Die Nutzer sollten über ein Suchfeld verfügen, damit sie relevante Inhalte einfach und schnell finden können.
• Kommentarbereich: Nutzer haben möglicherweise die Möglichkeit, Beiträge und Anleitungen zu kommentieren und ihre Meinung zu äußern. 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. Eine Art Blog sollte also auf der Landingpage vorhanden sein.
• Schnelle Entwicklung: Die meisten SSG-Frameworks (Static Site Generator) werden auf dem Server ausgeführt. Änderungen an der Datei werden sofort in der Benutzeroberfläche übernommen. Außerdem sollte der Bereitstellungs- und der Erstellungsprozess einfach sein. Wenn wir in Zukunft das Framework ändern möchten, verwenden wir. Dann sollte es einfach sein. Die meisten Frameworks unterstützen das Schreiben von Markdowns, sodass nur das Verschieben der MD-Dateien und wenige Änderungen ausreichen sollten.
Hier teile ich die vorhandenen Website-Seiten in neue Website-Bereiche und -Seiten auf :
• Landingpage:
Die Landingpage sollte auf die wichtigsten Features des gRPC-Gateways hinweisen.
- Erste Schritte mit dem gRPC-Gateway (Weiterleitung zum Nutzerhandbuch)
- Einfache Installationsanleitung (kurze Befehle)
- Vorteile des gRPC-Gateways
- Projekt mit gRPC-Gateway
Die Grundidee ist also, statt einer ausführlichen Beschreibung die wichtigsten Punkte auf der Landingpage anzuzeigen und einen Link bereitzustellen, über den Sie weitere Details aufrufen können.
• Seite mit Nutzerhandbuch für das gRPC-Gateway:-
- Installationsanleitung.
- Kurzanleitung mit gRPC-Gateway.
• Seite mit Entwicklerleitfaden für gRPC-Gateway:-
Der Entwicklungsleitfaden, der Beitragsleitfaden, die Git-Einrichtung, der Verhaltenskodex, die Dokumentation, der Entwicklungsworkflow usw. verweisen auf ähnliche Seiten. Daher müssen alle Dateien refaktoriert und neu angeordnet werden. Die Hauptentwicklungsseite sollte alle diese Seiten enthalten. Der Hyperlink wird in jedem Schritt erstellt.
• Informationen zur Seite "gRPC-Gateway":-
Die Liste aller Mitwirkenden sollte in Teambereichen enthalten sein. Quick Links und Versionshinweise. Die neuesten Blogs werden hinzugefügt, um den Nutzer zu motivieren, sich über aktuelle Neuigkeiten zum gRPC-Gateway zu informieren.
• Blogs, Versionshinweise und Anleitungen:
Meiner Meinung nach sollte diese Website eine Blogging-Option haben. So können Neuigkeiten und Veröffentlichungen leicht kommuniziert werden. Die Anleitungsseite 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 obige Aufgabe abgeschlossen haben, aktualisieren Sie die gleichen Änderungen im v2-Zweig und nehmen Sie diese Änderungen auch mit dem Master-Zweig des gRPC-Gateway vor.
SEKUNDÄRES ZIEL DIESES PROJEKTS:-
Weitere Änderungen müssen vorgenommen werden, um die gRPC-Gateway-Dokumentation robuster und lesbarer zu machen:
• Grammatik- und Schreibfehler beheben sowie Links und Beiträge auf der Website in allen vorhandenen Dateien von gRPC-Gateway organisieren und ausrichten.
• Fügen Sie bei Bedarf weitere Dokumentation und Inhalte in gRPC-Gateway hinzu, da für die meisten Features nur eine sehr kurze Dokumentation verfügbar ist, z. B. im Dokumentationsabschnitt der Website zu AWS, Background and Usage usw.
• Go Snippets-gRPC-Gateway gemäß den Gofmt-Formaten refaktorieren
Nachdem Sie die obige Aufgabe abgeschlossen haben, aktualisieren Sie die gleichen Änderungen im v2-Zweig und nehmen Sie diese Änderungen auch mit dem Master-Zweig des gRPC-Gateway vor.
WARUM BIN ICH DIE RICHTIGE PERSON FÜR DIESES PROJEKT:
Ich glaube, ich bin die richtige Person für dieses Projekt, weil:-
• Ich habe bereits Erfahrung mit der Verbesserung der Dokumentation von Organisationen und kann jedes Versionskontrollsystem verwenden. Die Ausführung von Befehlen auf GitHub wird also kein Problem sein. • Was mich außerdem antreibt, ist die Arbeit an Projekten, die einen Mehrwert für die Menschen schaffen. Wenn Sie möchten, dass jemand etwas möglichst effizient macht, dokumentieren Sie das. Durch die Dokumentation Ihrer Prozesse sorgen Sie für Effizienz, Einheitlichkeit und ein beruhigendes Gefühl für alle Beteiligten. • Ich bin mit dem Workflow und der Codebasis von gRPC-Gateway vertraut, da ich in den letzten zwei Monaten zu gRPC-Gateway beigesteuert und 11 PR zusammengeführt habe.