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:
- Creative Commons
- Technischer Redakteur:
- nimishnb
- Projektname:
- Leitfaden zur Verwendung von Vokabular
- Projektdauer:
- Standardlaufzeit (3 Monate)
Projektbeschreibung
Projektübersicht
Vocabulary hat ein enormes Potenzial, als primäre Bibliothek für UI-Komponenten zum Erstellen von Websites verwendet zu werden. Es braucht eine robuste, aber für Laien verständliche Anleitung. Wichtige Entwicklerinformationen wie Komponentenleitfäden, Nutzungsspezifikationen und Konfigurationsoptimierungen sind ein wesentlicher Bestandteil jeder Dokumentation. Dadurch bekommen bestehende Nutzer ein Gefühl dafür, wie ihr Vokabular weiter wächst und neue Meilensteine erreicht, und es wird die Verwendung des Vokabulars in vergleichsweise neueren Projekten gefördert. Die gewünschten Ergebnisse meiner Praktikumszeit umfassen nicht nur die Erstellung eines prägnanten Leitfadens zur Verwendung der vorhandenen Komponenten, sondern auch das Entwerfen und Entwickeln einer Startseite (mit integrierter Dokumentation für jede) für Vocabulary, Vue-Vocabulary und Fonts.
Projektplan
Das Problem: Die Dokumentation ist einer der Hauptgründe, warum eine bestimmte Open-Source-Bibliothek erfolgreich sein wird. Die wichtigste Frage, die sich Entwickler bei der Auswahl eines geeigneten Technologie-Stacks für ihre Anwendungen stellen, lautet: „Ist die Bibliothek gut dokumentiert? Ist sie gut gepflegt? Bietet es eine angemessene Unterstützung bei Nutzung und Fehlern?“ Genau diese Fragen sollten wir uns bei dieser Projektidee stellen. Aus Sicht des Softwareentwicklungsteams:
Anforderungenanalyse: Es besteht ein dringender Bedarf an einer prägnanten und konsolidierten Dokumentation für unsere Anforderungen. Die fehlende Dokumentation beeinträchtigt die zukünftigen Perspektiven von Open-Source-Anwendungen und ist bei Weitem eine wesentliche und nicht vernachlässigbare Komponente. Diese Dokumentationen sollten auf einer ansprechenden Startseite verlinkt werden, auf der sie sofort das Interesse der Nutzer weckt. Die Dokumentation sollte gut organisiert sein, damit sie sich nahtlos durchgehen lässt.
Spezifikationen: Je nach Anforderungen können Spezifikationen festgelegt werden. Der Inhalt der Dokumentation kann aus Daten auf den CC-Netlify-Websites sowie aus bekannten Quellen wie Semantik-UI, scikit-learn, Numpy, Bootstrap usw. gebildet werden. Die Ausgabe dieser Aufgabe wäre die erforderliche Landingpage und die vollständigen Dokumentationsleitfäden.
Einige allgemeine Probleme im Zusammenhang mit Vokabeln, Vokabular und Schriftarten:
Es gibt keine Dokumentation. Und wenn es welche gibt, sind Teile davon auf den Netlify-Websites verstreut. Nutzer, Entwickler oder externe Mitwirkende können dann nicht auf unsere Bibliothek zugreifen.
Es sind zusätzliche Klicks erforderlich, um eine bestimmte Komponente aufzurufen und den entsprechenden Code zu kopieren. Eine einfache Google-Suche nach etwas wie „Tabs-Komponente CC Vokabular“ liefert nicht die gewünschten Informationen. Eine Suchoption in den Dokumentationshandbüchern würde die UX erheblich verbessern.
Eine etwas ausführlichere Beschreibung der Komponenten, in der auch weniger offensichtliche Details beschrieben werden.
Keine Option für die Live-Ausführung. Eine Live-Ausführung wird von verschiedenen Websites wie JSFiddle unterstützt. So können Entwickler sich ein Bild von der Komponente machen, ohne eine ganze Anwendung ausführen zu müssen.
Die Lösung
Es gibt mehrere mögliche Lösungen. Ich werde hier jedoch auf einige eingehen und meine endgültige Lösung im Abschlussteil vorstellen:
= Die Verwendung von readthedocs readthedocs ist eine bekannte Lösung zum Schreiben von Dokumentation für Open-Source-Bibliotheken. Es basiert auf dem Python-Dokumentationstool Sphinx.
Vorteile:
- Eine weit verbreitete Form der Dokumentationserstellung, die von Organisationen wie Ethereum (Solidity) verwendet wird.
- Optimal strukturierte Dokumentation
- Kostenloses statisches Hosting.
Nachteile:
- Keine absolute Kontrolle über das Styling.
= Mit Sphinx Wir könnten Sphinx auch nativ für die Dokumentation verwenden, da sie für all unsere Zwecke gute Funktionen bietet.
Vorteile:
- Das beliebteste Python-Tool für die Dokumentation.
- Bietet auch Unterstützung für die Suche nach Dokumentation.
- Das Standard-CSS kann durch ein benutzerdefiniertes CSS überschrieben werden. Mit .rst-Dateien kann HTML teilweise gesteuert werden.
Nachteile:
- Erforderlich wäre das Programmieren in Python und das ReStructured Text-Format (.rst), was eine Abweichung von den vorgeschlagenen Projektsprachen darstellt.
= Jekyll-Designs verwenden Jekyll-Designs sind in GitHub-Seiten eingebunden. Es gibt vordefinierte Vorlagen, die je nach Bedarf angepasst werden können.
Vorteile:
- Vordefinierte Dokumentationsthemen für alle Zwecke.
- Standard-CSS und -Stile können durch benutzerdefinierte Standards und Stile überschrieben werden. Auch die Steuerung von HTML ist möglich.
- Hier wird das Standard-Primer-CSS für das Erstellen der Seiten abgerufen.
- Einfache Einbindung in GitHub-Seiten
Nachteile:
- Bietet möglicherweise nicht die beste Strukturierung der Dokumentation.
=GitHub-Seiten verwenden Die standardmäßigen GitHub-Seiten zum Erstellen unserer statischen Website (HTML, CSS, JS).
Vorteile:
- Uneingeschränkte Kontrolle über fast alle fraglichen Inhalte.
- Maximale Flexibilität bei der Auswahl von Layout, Farben und Stilen.
- Einfache Verwendung von Wortschatzkomponenten
- Einfaches Einbetten von Code-Snippets und Links zum Ausführen in Echtzeit
Nachteile:
- Dies kann zeitaufwendig sein.
= Haroopad verwenden Hier wird stattdessen eine alternative Markdown-Lösung verwendet.
Vorteile:
- Es ist nur wenig komplizierte Programmierung erforderlich.
- Der Schwerpunkt liegt darauf, die Dokumentationen perfekt zu verfassen.
Nachteile:
- Mangelnde Kontrolle über Preisvergleichsportale.
- Die Community bietet möglicherweise nicht den besten Support.
- MDX wird möglicherweise nicht unterstützt.
= MKDocs verwenden Stattdessen gibt es eine andere alternative Markdown-Lösung.
Vorteile:
- Es würde (wieder) nur wenig kompliziertes Programmieren erfordern.
- Der Ansatz „Mehr schreiben, weniger Code“
Nachteile:
- Fehlende Kontrolle über CSS.
- Bietet möglicherweise nicht den besten Community-Support.
- Es wird Python verwendet. Möglicherweise muss auch eine Amazon S3-Instanz gestartet werden.
= Verwendung von VueJS und StorybookJS Dieser Ansatz wird häufig für das Vokabular und seine Schwester-Repositories verwendet.
Vorteile:
- Sich an Technologien halten, die aufgrund früherer Berufserfahrungen garantiert funktionieren.
- Kenntnisse der Codebasis
- Keine geeignete Technologie in diesem Bereich.
Nachteile:
- Für den gleichen Zweck können auch einfachere Optionen verfügbar sein.
Zusammenfassend würde ich sagen, dass der Ansatz mit VueJS + Storybook (HTML,CSS,JS) am besten geeignet ist, da ich damit auch vertraut bin. Dies würde jedoch auch bedeuten, dass wir bei der Entwicklung dieser Anwendung nicht allzu viel Aufwand betreiben. Außerdem wäre es ziemlich einfach, CC-Vocabulary-Komponenten zu verwenden. Bei der Entscheidung über die Struktur der Dokumentation sollten wir jedoch unbedingt berücksichtigen, wie die Inhalte in den Zwischenüberschriften in der Dokumentation zu lesen sind. Ich war von der Semantic-UI-Website (für die StoryBook) beeindruckt, da sie ein minimalistisches Design hat und mit nur wenigen Klicks leicht zu finden ist, was sie wollen. Abgesehen von Semantic-UI habe ich mich auch mit Material Design, Primer, Bootstrap, Carbon Design usw. beschäftigt, um mich als UI-Designleitfäden und Designsysteme für meine Arbeit zu verwenden. Wir können uns auch fertige Jekyll-Dokumentationsthemen ansehen, um uns inspirieren zu lassen.