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:
- Creative Commons
- Technischer Redakteur:
- Nimshnb
- Projektname:
- Leitfaden zur Verwendung des Wortschatzes
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Projekt-Synopse
Vokabular hat immenses Potenzial, als primäre Bibliothek für UI-Komponenten für die Erstellung von Websites verwendet zu werden. Er benötigt eine solide, aber auch für Laien geeignete Anleitung. Wichtige Entwicklerinformationen wie Komponentenhandbücher, Nutzungsspezifikationen und Konfigurationsoptimierungen sind ein wesentlicher Bestandteil jeder Dokumentation. Dies wird nicht nur bestehende Nutzer dazu anregen, ein Gefühl dafür zu bekommen, wie ihr Wortschatz weiter wächst und neue Meilensteine erreicht, sondern auch die Verwendung von Vokabular in vergleichsweise neueren Projekten fördern. Für mein Praktikum würde ich nicht nur eine einfache Anleitung zur Verwendung der vorhandenen Komponenten erstellen, sondern auch eine Startseite für Vokabular, Vue-Wortschatz und Schriftarten entwickeln und erstellen, die jeweils zu einer integrierten Dokumentation führen.
Projektplan
Das Problem:Die Dokumentation ist einer der Hauptgründe, der ausschlaggebend dafür ist, wie erfolgreich eine bestimmte Open-Source-Bibliothek ist. Die Hauptfrage, die sich Entwickler bei der Auswahl eines geeigneten Technologie-Stacks für ihre Anwendungen stellen, lautet: „Ist die Bibliothek gut dokumentiert? Wird es gut gepflegt? Hat das Tool eine gewisse Nutzung und Fehlerunterstützung?". Genau diese Fragen sollten wir uns bei der Bewältigung dieser Projektidee stellen. Aus Sicht der Softwareentwicklung:
Anforderungsanalyse:Es besteht dringender Bedarf an einer prägnanten und konsolidierten Dokumentation. Die fehlende Dokumentation schadet der zukünftigen Perspektive von Open-Source-Anwendungen und ist bei Weitem eine unverzichtbare und nicht vernachlässigbare Komponente. Links zu diesen Dokumentationen sollten eine ansprechende Startseite sein, die sofort das Interesse der Nutzer weckt. Die Dokumentation sollte gut strukturiert sein und einen reibungslosen Ablauf ermöglichen.
Spezifikationen:Je nach Anforderungen können Spezifikationen festgelegt werden. Der Inhalt der Dokumentation kann aus Daten gebildet werden, die auf den CC Netlify-Websites vorhanden sind, und einigen bekannten Dokumentationen wie Semantik-ui, scikit-learn, numpy, Bootstrap usw. inspirieren. Das Ergebnis dieser Aufgabe sind die erforderliche Landingpage und die vollständigen Dokumentationsleitfäden.
Einige allgemeine Probleme im Zusammenhang mit Wortschatz, Vue-Wortschatz und Schriftarten sind derzeit:
Es gibt keine Dokumentation, und selbst wenn es welche gibt, sind Teile davon auf den Netlify-Websites verstreut. Nutzer, Entwickler oder externe Beitragende können unsere Bibliothek jedoch nicht verwenden.
Um zu einer bestimmten Komponente zu gelangen und den entsprechenden Code zu kopieren, sind zusätzliche Klicks erforderlich. Eine einfache Google-Suche nach etwas wie „Tabs component CC Vocabulary“ liefert nicht die gewünschten Informationen. Eine Suchfunktion in den Dokumentationsleitfäden würde die UX erheblich verbessern.
Eine etwas ausführlichere Beschreibung der Komponenten in Textform, in der die unbekannten Details beschrieben werden.
Keine Option für Liveausführung. Eine Live-Ausführung wird von verschiedenen Websites wie JSFiddle unterstützt. Entwickler können sich so einen Eindruck von der Komponente verschaffen, ohne eine ganze Anwendung laufen zu müssen, um zu sehen, wie sie funktioniert.
Die Lösung
Es gibt mehrere Lösungen. Ich möchte hier jedoch auf einige wenige Punkte eingehen und meine endgültige Lösung im Schlussteil vorstellen:
= readthedocs verwenden readthedocs ist eine bekannte Lösung zum Schreiben von Dokumentationen für Open-Source-Bibliotheken. Es basiert auf Sphinx, dem Python-Dokumentationstool.
Vorteile:
- Eine weit verbreitete Form der Dokumentationsgenerierung, die von Unternehmen wie Ethereum (Solidity) verwendet wird.
- Optimal strukturierte Dokumentation
- Kostenloses statisches Hosting.
Nachteile:
- Mangelnde absolute Kontrolle über den Stil.
= Verwendung von Sphinx Wir könnten Sphinx auch nativ für die Dokumentation verwenden. Es bietet gute Funktionen für alle unsere Zwecke.
Vorteile:
- Das beliebteste Python-Tool für die Dokumentation.
- Bietet auch Unterstützung für die Suche in der Dokumentation.
- Standard-CSS kann mit einem benutzerdefinierten CSS überschrieben werden; einige Kontrollen über HTML-Code mithilfe von RST-Dateien.
Nachteile:
- Er würde die Programmierung in Python und ein neu strukturiertes Textformat (.rst) umfassen, was eine Abweichung von den vorgeschlagenen Projektsprachen ist.
= Verwenden von Jekyll-Designs Die Jekyll-Designs sind in GitHub-Seiten integriert. Außerdem gibt es Vorlagen, die je nach Bedarf angepasst werden können.
Vorteile:
- Fertige Dokumentationsthemen für alle Zwecke.
- Standard-CSS und -Stile können mit benutzerdefinierten Stilen überschrieben werden. Sie können auch HTML-Code steuern.
- Ruft das standardmäßige Primer-CSS-Element zum Erstellen der Seiten ab.
- Einfache Einbindung von GitHub-Seiten
Nachteile:
- Bietet möglicherweise nicht die beste Dokumentationsstrukturierung.
=GitHub-Seiten verwenden Die standardmäßigen GitHub-Seiten zur Erstellung der statischen Website (HTML, CSS, JS).
Vorteile:
- Vollständige Kontrolle über fast alle betroffenen Inhalte.
- Maximale Flexibilität bei der Auswahl von Layout, Farben und Stilen
- Einfache Verwendung der Wortschatzkomponenten.
- Einfaches Einbetten von Code-Snippets und Live-Ausführungslinks.
Nachteile:
- Dies kann auch zeitaufwendiger sein.
= Verwendung von Haroopad Dies ist eine alternative Markdown-Lösung.
Vorteile:
- Wenig kniffliges Programmieren erforderlich.
- Der Fokus liegt darin, die Dokumentationen perfekt zu schreiben.
Nachteile:
- Mangelnde Kontrolle über CSS.
- Bietet möglicherweise auch nicht den besten Community-Support.
- MDX wird möglicherweise nicht unterstützt.
= Verwendung von MKDocs Dies ist eine alternative Markdown-Lösung.
Vorteile:
- Mit sehr wenig umständlicher Codierung (auch wieder)
- Mehr schreiben, weniger Code.
Nachteile:
- Mangelnde Kontrolle über CSS.
- Haben möglicherweise nicht den besten Community-Support.
- Verwendet Python. Unter Umständen muss zusätzlich eine Amazon S3-Instanz gestartet werden.
= VueJS + StorybookJS Dieser Ansatz wird häufig für Vokabular und zugehörige Repositories verwendet.
Vorteile:
- Wir setzen auf Technologien, die aufgrund früherer Berufserfahrungen garantiert einwandfrei funktionieren.
- Kenntnisse der Codebasis
- Keine kompetente Technologie in diesem Bereich.
Nachteile:
- Für dieselben Zwecke können auch einfachere Optionen angeboten werden.
Zusammenfassend lässt sich sagen, dass der Ansatz mit dem VueJS+Storybook-Ansatz (HTML,CSS,JS) am besten geeignet ist, da ich damit auch einverstanden bin. Dies würde jedoch auch bedeuten, dass wir uns bei der Entwicklung dieser Anwendung nicht völlig anstrengen werden. Die Verwendung von Komponenten für den Untertitelslogan wäre auch relativ einfach. Um die Struktur der Dokumentation festzulegen, sollten wir jedoch unbedingt berücksichtigen, wie der Inhalt in den Zwischenüberschriften in der readthedocs-Dokumentation aufgeteilt wird. Ich war von der Website mit Semantic-UI (die StoryBook verwendet) beeindruckt, da sie ein minimalistisches Design hat und man mit wenigen Klicks leicht das gewünschte Ergebnis finden kann. Neben der Semantic-UI habe ich mir auch Material Design, Primer, Bootstrap, Carbon Design usw. angesehen, die ich als UI-Styling-Leitfäden und Designsysteme für meine Arbeit verwendet habe. Wir können auch nach vorgefertigten Jekyll-Dokumentationsthemen suchen, um uns davon inspirieren zu lassen.