Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- Creative Commons
- Technischer Redakteur:
- Nimishnb
- Projektname:
- Leitfaden zur Verwendung des Wortschatzes
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Projekt-Zusammenfassung
Vokabular hat ein immenses Potenzial, um als primäre Bibliothek für UI-Komponenten für die Website-Erstellung verwendet zu werden. Sie benötigen dafür eine robuste, 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 fördert auch den Gebrauch des Vokabulars in vergleichsweise neueren Projekten. Für mein Praktikum hätte ich nicht nur eine einfache Anleitung für die Nutzung der bereits vorhandenen Komponenten ausarbeiten, sondern auch eine Startseite für Vokabular, Vokabular und Schriftarten entwickeln und für jeden eine integrierte Dokumentation erstellen müssen.
Projektplan
Das Problem: Dokumentation ist einer der Hauptgründe dafür, wie erfolgreich eine bestimmte Open-Source-Bibliothek ist. Die wichtigste Frage, die Entwickler bei der Auswahl eines geeigneten Technologie-Stacks für ihre Anwendungen haben, lautet: „Ist die Bibliothek gut dokumentiert? Wird es gut gepflegt? Ist sie in gewissem Umfang genutzt und unterstützt sie bei Fehlern?“ Genau diese Fragen sollten wir uns bei der Arbeit an dieser Projektidee stellen. Aus Sicht der Softwareentwicklung:
Anforderungsanalyse:Es ist unmöglich, eine prägnante und konsolidierte Dokumentation für unsere Anforderungen zu haben. Die fehlende Dokumentation schadet der Zukunft von Open-Source-Anwendungen und ist bei Weitem eine wichtige und nicht vernachlässigbare Komponente. Die Links zu diesen Dokumentationen sollten auf einer ansprechenden Startseite sein, die sofort das Interesse der Nutzer weckt. Die Dokumentation sollte gut strukturiert sein, damit ein reibungsloser Ablauf möglich ist.
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, sowie einer Anregung von bekannten Dokumentationen wie semantic-ui, scikit-learn, numpy, Bootstrap usw. Das Ergebnis dieser Aufgabe sind die erforderliche Landingpage und die vollständigen Dokumentationsleitfäden.
Einige allgemeine Probleme im Zusammenhang mit dem Vokabular, dem Wortschatz und den Schriftarten sind derzeit wie folgt:
Es gibt keine Dokumentation. Selbst wenn es solche gibt, sind Teile davon auf den Websites von Netflix verstreut. Nutzer, Entwickler oder externe Mitwirkende 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 „Tabskomponente CC-Vokabular“ liefert nicht die gewünschten Informationen. Eine Option zur Suche in den Dokumentationsleitfäden würde die UX erheblich verbessern.
Eine etwas ausführlichere Beschreibung der Komponenten in Textform, in der die unklaren Details beschrieben werden.
Keine Option für Live-Ausführung. Eine Live-Ausführung wird von verschiedenen Websites wie JSFiddle unterstützt, sodass Entwickler sich einen Eindruck von der Komponente verschaffen können, ohne eine ganze Anwendung ausführen zu müssen.
Die Lösung
Dafür gibt es mehrere Lösungsmöglichkeiten. Ich möchte hier jedoch auf einige wenige Punkte eingehen und meine endgültige Lösung im Fazit-Teil 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 weitverbreitete Form der Dokumentationserstellung, 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 nativ auch 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.
- Der Standard-CSS-Code kann mit einem benutzerdefinierten CSS-Code überschrieben werden .Mit RST-Dateien lässt sich der HTML-Code in gewissem Umfang steuern.
Nachteile:
- Er würde eine Programmierung in Python und ein neu strukturiertes Textformat (.rst) beinhalten, was eine Abweichung von den vorgeschlagenen Projektsprachen darstellt.
= Verwenden von Jekyll-Designs Jekyll-Designs sind in GitHub-Seiten integriert. Außerdem gibt es Vorlagen, die je nach Bedarf angepasst werden können.
Vorteile:
- Vorgefertigte Dokumentationsthemen für alle Zwecke.
- Standard-CSS und -Stile können mit benutzerdefinierten Stilen überschrieben werden. Sie haben auch Kontrolle über HTML.
- Es wird das standardmäßige Primer-CSS zum Erstellen der Seiten abgerufen.
- Einfache Einbindung in GitHub-Seiten.
Nachteile:
- Bietet möglicherweise nicht die beste Dokumentationsstrukturierung.
GitHub-Seiten verwenden Die standardmäßigen GitHub-Seiten zum Erstellen unserer 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 Vokabularkomponenten.
- Einfaches Einbetten von Code-Snippets und Live-Run-Links.
Nachteile:
- Die Lösung kann allerdings mehr Zeit in Anspruch nehmen.
Verwendung von Haroopad. Dies ist eine alternative Markdown-Lösung.
Vorteile:
- Mit wenig mühsames Programmieren.
- Konzentrieren Sie sich darauf, die Dokumentation perfekt zu schreiben.
Nachteile:
- Mangelnde Kontrolle über CSS.
- Vielleicht gibt es auch nicht den besten Community-Support.
- MDX wird möglicherweise nicht unterstützt.
= Verwendung von MKDocs Damit ist eine alternative Markdown-Lösung möglich.
Vorteile:
- Würde (auch wieder) ein Minimum an umständlichen Codierungen beinhalten.
- „Mehr schreiben, weniger Code“.
Nachteile:
- Mangelnde Kontrolle über CSS.
- Möglicherweise gibt es nicht den besten Community-Support.
- Verwendet Python. Unter Umständen muss zusätzlich eine Amazon S3-Instanz gestartet werden.
= VueJS + StorybookJS verwenden Dieser Ansatz wird häufig für Vokabular und zugehörige Repositories verwendet.
Vorteile:
- Die Bindung an Technologien, die aufgrund früherer Berufserfahrungen in jedem Fall einwandfrei funktionieren
- Kenntnisse der Codebasis
- Keine kompetente Technologie in diesem Bereich.
Nachteile:
- Für die gleichen Zwecke können auch einfachere Optionen vorhanden sein.
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. Das würde aber auch bedeuten, dass wir uns bei der Entwicklung dieser Anwendung nicht ganz auf den Weg machen werden. Es wäre auch ziemlich einfach, die CC-Vokabularkomponenten zu verwenden. Bei der Entscheidung über die Struktur der Dokumentation sollten wir jedoch unbedingt berücksichtigen, wie der Inhalt unter den Zwischenüberschriften in der readthedocs-Dokumentation aufgeteilt wird. Ich war von der Semantic-UI-Website beeindruckt, auf der StoryBook verwendet wird, da sie minimalistisch gestaltet ist und mit nur wenigen Klicks leicht zu erkennen ist, was sie wollen. Neben 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. Auch vordefinierte Jekyll-Dokumentationsthemen können wir uns inspirieren lassen.