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:
- Cloud Native Computing Foundation (CNCF)
- Technischer Redakteur:
- Syam Sundar K
- Projektname:
- Weitere und bessere Kubectl-Beispiele
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Ziel dieses Projekts ist es, den vorhandenen kubectl-Spickzettel und die Referenzdokumente zu erweitern.
Das sind die Ziele dieses Projekts: • Mehr und bessere kubectl-Beispiele erstellen. • kubectl-Beispiele zur kubectl-Übersicht hinzufügen. • Refaktorieren Sie kubectl docs für maximale Nützlichkeit.
Ziel I – Beispiele für kubectl:
Wir werden eng mit den speziellen Interessengruppen der Befehlszeile zusammenarbeiten, um den Kontext zu verstehen und zu dokumentieren, welche Beispiele sich die Kubernetes-Nutzer am meisten wünschen. Dies kann von der Verbesserung der vorhandenen kubectl-Befehle auf der Übersicht bis hin zum Hinzufügen neuer Befehle reichen.
Ziel II – Verbesserte Nützlichkeit von Dokumenten:
Um die Nützlichkeit der Dokumente zu verbessern, können Sie Folgendes tun:
• Eliminierung von Schwierigkeiten für Anfänger • Neuanordnung des kubectl-Befehls in einer bestimmten Reihenfolge, um Kontinuität im logischen Ablauf zu gewährleisten
Mit besserer Befehls- und Fallerklärung lassen sich Schwierigkeiten für Einsteiger eliminieren. Dies mag einfach erscheinen, kann Anfänger aber erheblich dazu bewegen, weiterzulernen oder den Lernfortschritt abzubrechen. Nehmen wir z. B. an, als ich mit Kubernetes über kubectl anfing, war ich mir nicht sicher, was die Unterschiede zwischen Pods und Bereitstellungen bedeuten. Zuerst habe ich einen in Node.js geschriebenen Back-End-Dienst bereitgestellt. Nach ein paar Stunden wollte ich es herunterfahren. Also habe ich versucht, den Pod zu löschen, aber aufgrund der selbstheilenden Natur der Pods wurden sie neu erstellt. Ich war irgendwie verwirrt darüber, was los war, und fragte mich, warum es neu erstellt und nicht gelöscht wurde. Nach einigen Suchen im Web habe ich festgestellt, dass das Löschen von Pods nicht dem Löschen einer Bereitstellung entspricht. Für ein geschultes Auge mag dies einfach erscheinen, aber eine klare Erklärung, die diese Art von Ambiguität beseitigt, ist das, was ein gutes Dokument von einem großartigen Dokument unterscheidet.
Neuanordnung des kubectl-Befehls in einer bestimmten Reihenfolge, um Kontinuität im logischen Ablauf sicherzustellen. Wenn Sie wie ich Geschichtenerzähler sind, fragen Sie sich wahrscheinlich, wie Sie Storytelling-Elemente in ein Tabellenblatt mit einer Liste von Terminalbefehlen einbinden. Alles, was wir lernen, hat einen logischen Ablauf: einen Start- und einen Endpunkt. kubectl als Befehlszeilentool hat offensichtlich eine Lernkurve. Die Lernkurve entspricht der Lernkurve von Kubernetes selbst. Da fast jeder mit Kubernetes über kubectl beginnt (außer für Leute, die Web-UI verwenden) und die Lernkurve eng mit der Lernkurve von Kubernetes gekoppelt ist, lässt sich die Dokumentation deutlich verbessern, indem man einfach die Reihenfolge dieser Befehle ändert und Storytelling-Elemente einfügt. Nehmen wir einmal an, dass Funktionen wie das horizontale Pod-Autoscaling erklärt werden, nachdem Ressourcen mit echten Beispielen und Illustrationen erläutert wurden.
Ziel III: Verbesserte Benutzerfreundlichkeit von Google Docs:
Die vor Kurzem durchgeführte Migration der Kubernetes-Website zu Docsy Hugo ist eine enorme Veränderung in der Dokumentationsperspektive. Obwohl die Migration erfolgreich war, gibt es immer noch Raum für viele Verbesserungen im Dokumentenbereich.
Hier sind einige Änderungen, die ich vorschlagen würde.
• Automatisches Scrollen im linken Bereich zum aktuell aktiven Bereich der Hauptdokumente: Dies kann hilfreich sein, um den Überblick über aktuelle, anstehende und vergangene Abschnitte zu behalten. • In die Zwischenablage kopieren: Einige Befehle können sehr langwierig sein. • Inhaltsformatierung von DOC-Dateien: Nach der Migration wurden die Inhalte einiger Seiten nicht richtig formatiert, z. B. im Abschnitt „Ressourcentyp“ in der kubectl-Übersicht. Dies beeinträchtigt die Nutzererfahrung.
Diese Änderungen können die Nutzerfreundlichkeit auf der Kubernetes-Website verbessern und auch die Produktivität der Nutzer steigern.