Eugene Ghanizadeh im Interview zu CODEDOC

„CODEDOC unterstützt eine erweiterte Syntax für Markdown, wodurch individuelle strukturelle Komponenten verwendet werden können“
Keine Kommentare

CODEDOC hilft dabei, Dokumentationen für Open-Source-Projekte zu schreiben und zu veröffentlichen. Dafür wird einfaches Markdown verwendet, das um eigene Komponenten ergänzt werden kann. Wie der Entwickler des Projekts, Eugene Ghanizadeh, im Interview erklärt, können Entwickler das Ergebnis so ganz individuell gestalten.

Entwickler: Was ist CODEDOC?

Eugene Ghanizadeh: Es handelt sich um ein Open-Source-Tool, mit dem man JAMStack-Dokumentations-Websites aus Markdown-Dateien erstellen und sie auf einem Dienst wie GitHub Pages hosten kann. Man installiert eigentlich nur das CLI, fügt es dem Projekt hinzu (beispielsweise einem Open-Source-Projekt auf GitHub), schreibt einige Markdown-Dateien und dann erstellt CODEDOC eine produktionsreife JAMStack-Seite, die man auf GitHub Pages veröffentlichen kann, indem man nur den Code dorthin schiebt.

Entwickler: Für welche Art von Projekte ist CODEDOC gedacht?

Ghanizadeh: Vor allem ging um unsere eigenen Open-Source-Projekte auf CONNECT-platform. Das Unternehmen hat sich zum Ziel gesetzt, Entwicklungswerkezeuge bereit zu stellen, die die Softwareentwicklung leichter machen, vor allem für kleinere Teams. Wir wollen sie in die Lage versetzen, viel mehr mit den begrenzten Ressourcen zu erreichen, die ihnen zur Verfügung stehen. Das meiste, was wir dafür machen, haben wir als Open-Source-Projekte veröffentlicht. Wir haben dabei viele Tools wie GitBook und sogar Medium-Artikel ausprobiert, aber keins davon hat unsere Anforderungen erfüllt. CODEDOC war ursprünglich ein spezifisches Skript für die Dokumentation von CONNECTIVE. Als die Zahl der Projekte, die eine Dokumentation benötigen, wuchs (parallel zu der Menge zukünftiger Projekte auf unserer Roadmap), habe ich entschieden, es zu einem eigenständigen, wiederverwendbaren Tool weiterzuentwickeln.

Seitdem ich es veröffentlicht habe (was noch gar nicht lange her ist), haben auch schon einige Leute damit begonnen, Tech-Blogs und -Tagebücher mit CODEDOC zu erstellen, was eine interessante Richtung für weitere Erkundungen ist. Ein Beispiel: Ich werde höchstwahrscheinlich auch unseren eigenen Tech-Blog von Medium in einen selbst erstellen Blog auf Basis von CODEDOC verlagern, und dabei auch die notwendigen Integrationen und Anpassungen vornehmen.

International JavaScript Conference

Effective Microservices Architecture In Node.js

by Tamar Stern (Palto Alto Networks)

React Components And How To Style Them

by Jemima Abu (Telesoftas)

Angular Camp 2020

Als Online- oder Präsenztraining!

Das 360°-Intensivtraining mit Angular-Koryphäe Manfred Steyer
Präsentiert von Entwickler Akademie

Entwickler: Es gibt ja bereits einige Tools, mit denen man Dokumentationen erstellen kann. Welche Features unterscheiden CODEDOC von anderen Optionen?

Ghanizadeh: Die wichtigsten Unterschiede können hier nachgelesen werden. Vor allem sind das folgende Features:

  • Jedes Dokument ist in Markdown geschrieben, sodass es ziemlich einfach und unproblematisch ist, sie zu schreiben. CODEDOC unterstützt eine erweiterte Syntax für Markdown, wodurch individuelle strukturelle Komponenten verwendet werden können, wie Buttons, Tabs, einklappbarer Content und so weiter. Man kann ganz leicht individuelle Komponenten schreiben und sie in Markdowns verwenden. Das macht CODEDOC sehr gut erweiterbar.
  • Code-Snippets sind mit Features angereichert, die spezifisch für eine erleichterte Lernbarkeit da sind. Dazu gehören Funktionen wie das Code-Highlighting, Hinweise, Referenzen und mehr. All diese Features können per Markdown genutzt werden.
  • CODEDOC wurde um die Erweiterbarkeit herum entworfen. Vom Projekt-Setup bis zur Ästhetik und den Layouts ist alles leicht konfigurierbar. Statt in Form einer Black Box daher zu kommen, erstellt das CODEDOC CLI Tool viel Boilerplate-Code zusammen mit der Konfiguration des Projekts, um Entwickler aktiv dazu einzuladen, daran herumzubasteln und es an ihren eigenen Bedarf anzupassen.
  • Vermutlich kein großes Feature, aber doch bemerkenswert: Die meisten Alternativen da draußen unterstützen keinen Dark Mode out-of-the-box. Das heißt, dass die meisten Dokumentationen auch keinen Dark Mode haben. Als Entwickler verbringe ich viel Zeit damit, Dokumentationen zu lesen, was die Abwesenheit einer guten Dark-Mode-Integration besonders schmerzhaft für meine Augen macht. Während der Entwicklung von CODEDOC haben wir intern gescherzt, dass „Eugene das macht, weil GitBook den Dark Mode hinter die Paywall gesetzt hat“.

Entwickler: Was steckt unter der Haube von CODEDOC?

Ghanizadeh: CODEDOC wurde für die Dokumentation einiger unserer Open-Source-Projekte entwickelt und baut zugleich auf ihnen auf. Am wichtigsten ist CONNECTIVE HTML, eine schlanke JSX/TSX-basierte Bibliothek, die auf DOM APIs aufbaut und Integrationen mit RxJS und CONNECTVE für reaktive und interaktive Logik bietet. Ebenfalls ein wichtiger Teil der Basis ist CONNECTIVE SDH. Das ist ein Framework, mit dem man JAMStack-Apps und -Websites bauen kann, indem es einen gemeinsamen Pool an Komponenten auf der Client- und der Server-Seite verwendet. Es arbeitet mit RxLine, einer Bibliothek für das Task-Pipeline-Management, die auf RxJS basiert, sowie @connectv/marked. Diese Library steckt hinter der Verwendung von JSX/TSX-basierten Komponenten im von Markdown.

Außerdem wird eine ganze Menge weiterer Open-Source-Tools verwendet (vor allem durch die genannten Bibliotheken), eine umfassende Liste kann hier gefunden werden. Ich glaube, unter diesen Tools sollte ich inbesondere noch Color Hunt hervorheben. Das ist ein wirklich praktisches Tool zur Auswahl von Farben.

Entwickler: Wie kann die Dokumentation, die von CODEDOC erzeugt wird, genau individualisiert werden – welche Optionen stehen zur Verfügung?

Ghanizadeh: Wie bereits erwähnt, kann fast alles an der erstellten Dokumentation individualisiert werden. Von einfachen Änderungen, wie einer Anpassung des Farbschemas und der Schriftart, bis hin zu komplett veränderten Layouts und eigenen Layout-Komponenten (oder In-Markdown-Komponenten), bis hin zur Änderung des Standard-APIs für die Suche oder der Integration anderer APIs. Beispielsweise wurde schon nach einer Möglichkeit gefragt, das Layout des Hamburger-Menüs zu verändern, das das ToC öffnet. Darum habe ich dieses Rezept zur Dokumentation hinzugefügt, als Anleitung dafür.

Entwickler: Vielen Dank für das Interview!

Eugene Ghanizadeh stammt aus dem Iran und ist derzeit Student im Master-Studiengang Informatik an der TUM. Er arbeitet in Teilzeit an Lösungen für den Datenschutz (ECOMPLY.io). Seine freie Zeit steckt er in CONNECT-platform und Projekte wie CODEDOC. Eugene hat einen Bachelor-Abschluss in Informatik und hat einige Jahre im Iran in der IT-Branche gearbeitet, bevor er nach Deutschland kam, um sein Studium fortzusetzen. Beruflich war er hauptsächlich als UX Designer, Produkt-Manager, Team Lead tätig, nicht als Software-Ingenieur. Im Iran hat er vor allem für CafeBazaar gearbeitet und ist dort immer noch als UX-Consultant tätig.
Unsere Redaktion empfiehlt:

Relevante Beiträge

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu:
X
- Gib Deinen Standort ein -
- or -