Kick as Developer Docs so haben wir bei uns intern das Projekt
genannt, was zu einer richtig guten Dokumentation für
Developer auf unserer Plattform führen soll.
Konzepte erklären, apis beschreiben, Tutorials
bereitstellen doch was macht eigentlich eine richtig gute
developer Dokumentation aus, wer schreibt sie am Ende, wie hält
man sie aktuell und welche Plattform nutzt man dafür
eigentlich? All diese Fragen haben wir uns
gestellt und diskutieren sie in dieser Folge.
Und damit herzlich Willkommen zu einer neuen Folge des To do
Cast, dem deutschen Developer Podcast heute mit einer
Themenfolge und Robin Manuel, Du hast ein Thema aus deinen
letzten Wochen Berufsalltag mitgebracht.
Ich bin sehr gespannt, was ich hier heute auch Neues lernen
werde, ist ein super spannendes Thema.
Robin Manuel, Du bist ja Director AI und Cloud beim Eco.
Commerce, Softwareunternehmen Jtl und Berichte so ein bisschen
heute aus einem deiner Projekte. Ich selber für die, die nicht so
oft zuhören, bin Solutions Engineer bei github, den Podcast
machen wir aber natürlich in unserer Freizeit, auch wenn wir
heute über ein Thema aus unserem Alltag sprechen.
Genau, alleine an der Uhrzeit, in der wir das hier aufnehmen,
müsste man eigentlich, also das kriegt ihr jetzt natürlich nicht
mit, aber sieht man schon ganz klar, dass wir das hier nicht in
unserer Arbeitszeit machen. Und dafür, dass wir so lange
wach bleiben und auch für euch abends spät Podcast Rekorden da
hilft natürlich auch der ein oder andere Koffein Boost und
auch da müssen wir Dankeschön sagen an euch, denn ihr, die
Community, habt uns Kaffee ausgegeben.
Und zwar haben wir diese Woche 5 Kaffee von Daniel bekommen und
einen Kaffee von Alex. Vielen Dank dafür.
Wenn auch ihr uns einen Kaffee ausgeben wollt, um dafür zu
sorgen, dass wir auch weiterhin podcastfolgen spätabends
produzieren können, dann findet ihr einen Link zu bimi a Coffee
in den Shownotes. Da kann man uns cafés spenden
und wir freuen uns immer wie die kleinen Schneekönige darüber.
Ganz, ganz lieben Dank auch an die.
Ja, schon vielen, vielen Folgen, die ihr unsere Community hier
mit Kaffee unterstützt habt. Und damit steigen wir ins Thema
ein und du hast es in der Intro schon gesagt, wir reden heute
über Kick ass, Developer Dogs, erzähl uns mal.
Woher kommt der Name? Ja, es ist ein interner
Projektname und jetzt tatsächlich von einem Projekt
bei uns, bei Jtl, wie wir es genannt haben, wir vielleicht
ganz kurz so zum Hintergrund und zum zum Einstieg.
Wir bauen eine Cloud Plattform für Händlerinnen und Händler für
den für den E Commerce quasi. Und die lebt davon, dass nicht
nur wir da Sachen bauen, sondern dass wir auch ganz viele Partner
haben, die ihre Lösungen auf unserer Plattform bereitstellen.
Heißt die Apps für unsere Plattform programmieren und
damit reicht es nicht, einfach nur eine App zu programmieren,
man kann sich in die Plattform integrieren, wir haben bestimmte
Konzepte, die wir erklären müssen, du kannst dich zum
Beispiel. Weiß nicht einfach das Beispiel
ist, du willst jetzt dem User oder der Benutzerin eine
Benachrichtigung ausspielen, musst du nicht selber
Notification System bauen, kannst du das von der Plattform
nutzen, dich oben in so eine Glocke, die oben in der in der
Leiste ist integrieren und kannst natürlich auch mit den
apis sprechen, also mit dem ERP was wir bereitstellen und so
weiter und sofort also du kannst dich irgendwie diese Plattform
integrieren, du musst auf irgendeine bestimmte Art und
Weise eine App bereitstellen, du kannst unsere Login dann dafür
nutzen und das muss alles dokumentiert werden.
Und da dieses Partner Ökosystem so essentiell wichtig ist, auch
natürlich für den Erfolg unserer Plattform müssen, haben wir uns
gesagt, okay, es ist ein strategisch wichtiges Projekt
für uns, eine absolute Killer Developer Dokumentation zu
bauen. Ja, vor dem Hintergrund haben
wir uns gefragt, was ist denn überhaupt eine richtig, richtig
gute developer Dokumentation, Wir sind eine Software Company,
da gibt es bestimmt noch viele Meinungen dazu.
Aber ja, wie bauen wir denn selber eine?
Was haben wir denn vielleicht schon für coole Sachen in
unserem Alltag gesehen und wer baut sie denn am Ende und wer
baut sie am Ende, wenn ihr jetzt vielleicht sagt, Ey mir hat die
Folge so gut gefallen, ich würde die gerne bauen, dann an der
Stelle vielleicht auch noch mal ganz kurz der Hinweis, wir
heiern also wir suchen auch immer noch Leute, das klingt
Developer, Cloud Experten, KI Engineers, aber auch halt Leute,
die vielleicht sehr gut Dokumentationen schreiben
können, also Technical Writer oder sowas, schaut euch mal um
wir. Genau, ganz kleiner Werbeblock.
Hier haben die Stellenangebote von Jtl in den Show Notes
verlinkt werbeblockende und könnt euch natürlich auch
initiativ bewerben, aber das so ein bisschen so als Framing, wie
ich überhaupt auf das Thema kam. Das heißt, ihr baut Produkte für
Unternehmen, die Software entwickeln, e Commerce Software
unternehmen und dementsprechend sind ja eure Kunden nicht nur
irgendwelche anonymen Unternehmen, sondern Developer
wie sie auch hier zuhören. Und ich glaube Developer ist.
Aber kennen das? Man schaut, schaut in eine neue
Technologie rein und geht dann als erstes mal irgendwie in die
Dokumentation und schaut, wie komme ich da zurecht und da
entscheidet sich glaube ich schon ganz am Anfang schon quasi
an der Eingangstür, ob am Ende es zu einer erfolgreichen
Nutzung kommt, weil ich glaube, wenn ich da reinschaue und
irgendwie direkt erschlagen werde von einer Wall of Tax oder
das Ganze für mich extrem schwer.
Wert zu konsumieren ist. Dann drehe ich mich direkt
wieder um und schaue mir die nächste Seite an.
Aber ich denke mal, das ist so auch der Hintergrund, warum das
für euch so wichtig ist. Ja, Developer Dogs sind ja
zumindest für Developer auf der erste Kontakt mit dem Produkt
und das hält ja auch der erste Eindruck.
Und ja, auch wenn ich mir so angucke, was ich im Alltag
benutze oder was wir teilweise auf unserer Plattform einbauen
irgendwie, ich habe es auch schon mal irgendwo im Podcast
gesagt, so fast jedes richtig gute developer Produkt was ich
kenne. Oder was mir in Erinnerung
geblieben ist, hat eine geile Dokumentation.
Also ich denke da irgendwie sowas an.
Ich glaube das erste Mal, dass ich mit einer richtig guten
Dokumentation in Verbindung gekommen bin, war OZ Zero, da
hatte ich erstmal so einen blauen Effekt, da meldest du
dich mit deinem Account an und dann haben die die Codebeispiele
Vorausgefüllt mit deinen, mit deinen Variablen, mit deiner ten
id und sowas. Aber auch wie Stripe und Twilio,
das sind ja unter anderem so gute Produkte, weil sie so
developer friendly sind. Ja, das sind natürlich auch
alles Produkte, die sich primär an Softwareunternehmen richten,
die irgendwie eigene Produkte bauen, in die sie sich dann
integrieren müssen. Und von daher könnte man ja auch
schon sagen, das ist Teil des Produktes und wenn dieser Teil
des Produktes schlecht ist, dann.
Dann wird am Ende niemand dieses Produkt kaufen, weil häufig ist
es ja so, dass nicht irgendwelche weiß nicht
Entscheider, irgendwelche Business Leute dann am Ende
sagen okay wir nehmen diese oder diese Technologie, sondern die
ersten, die damit in Berührung kommen, sind halt die
technischen Teams, die Developer, denen man vielleicht
sagt, Wir haben hier folgende Sachen zur Auswahl, schaut euch
das einfach mal an, schaut euch mal die Doku an und gebt uns mal
Feedback, was gut funktioniert. Ich glaube, das unterschätzt man
auch total oft. Also ich glaube, das Business
gibt ja irgendwie schon sowas vor wie weiß nicht, wir brauchen
Feature flags und bei uns läuft zumindest so, dann gehen die
Developer hin, schauen, machen ein paar Proof of Concepts,
evaluieren Technologien, schreiben dann bei uns Konzepte,
wir halten auch immer alles in sogenannten AD RS, also
Architecture Decision Records fest, wo dann alle Sachen, die
zur Auswahl standen beschrieben wurden und man dann so ein
bisschen die Pros und Cons da auflistet, dass man so, dass man
sich halt einfach auch in ein paar Jahren oder ein paar
Monaten. Noch mal rückblickend daran
erinnern kann, warum haben wir damals uns eigentlich für dieses
oder jenes Pattern oder auch Produkt entschieden?
Und da geben die Developer natürlich auch eine ganz klare
Empfehlung raus und man kennt das ja irgendwie.
Manche, manche Dokumentationen geben einem einfach ein gutes
Gefühl als Developer und da wollten wir jetzt so ein
bisschen auf die Reise gehen, weil fehlende oder schlechte
Docs mit Sicherheit auch so ein wieso ein Silent Deal breaker
sind, möchte ich aber irgendwie sagen, wo du dann im übrigen
vielleicht gar nicht merkst. Dass jemand dein Produkt sich
gegen dein Produkt entschieden hat oder auch turned, also zu
einem Konkurrenzprodukt wechselt, weil jetzt Developer
da jetzt auch bestimmt nicht wahnsinnig viel Feedback danach
irgendwie geben und oft verstehst du gar nicht warum und
in seltensten Fällen findest du raus, es war eine schlechte
Developer Dokumentation und was ist eine schlechte und was ist
eine Gute? Das versuchen wir so ein
bisschen rauszufinden, aber ich bin völlig bei dir, ist kein
nice to have mehr ist eigentlich Teil der Produktstrategie und.
Ich glaube, das hängt immer so ein bisschen davon ab, was für
eine Art von Produkt du baust. Ich glaube, bei manchen
Produkten ist vielleicht immer noch UI Forest, weil es sich
irgendwie an Endbenutzer richtet und dann gibt es zusätzlich noch
eine API für die technische Integration, da ist das
vielleicht nicht so entscheidend für die Kaufentscheidung, aber
man kann, glaube ich, ganz viel von diesen Companies, wie ihr es
seid, lernen, die halt sich primär an Developer richten,
weil was hindert halt eine Company die nicht so.
Für Developer baut daran ihre API Dokumentation genauso gut zu
machen und da den Leuten wirklich auch die die technische
Integration bauen, eine genauso gute Erfahrung zu liefern.
Eben, und das muss man bei uns ja sagen, die Company an sich
richtet sich gar nicht primär an Developer, sondern eigentlich
primär an Händlerinnen und Händler.
Aber wir, da wir eine Plattform bauen.
Ist eine Plattform einfach auch essentiell davon abhängig, dass
auf dieser Plattform mehr als nur First Party Apps passieren,
lasse ich mich zum Beispiel eine Integration in die gängige
Produktlandschaft, die es da draußen nur für den E Commerce
gibt, das anbietet, das kann man gar nicht selber bauen und dann
lebt das natürlich davon, dass Integrationen von anderen gebaut
werden, um die Plattform erfolgreich zu machen und
deswegen ist für uns das auch noch mal wichtig.
So ein developer Doku zu bauen. Und Du hast mir im Vorgespräch
erzählt vom 15 Minuten Test kannst du da noch mal ein
bisschen was zu sagen? Ja, das versuchen wir jetzt
immer. Also weil wir versuchen, jetzt
zu gucken, ob wir irgendwie jemanden finden, der noch nie
mit unserer Plattform gearbeitet hat und ob die Person es in 15
Minuten schafft, einen also irgendwas zum Laufen zu bringen.
Bei uns ist das eine Hello World App auf die Plattform zu
Deployen, die mindestens eine von unseren Integrationen
benutzt, und wir sind eine große Gruppe, so eine
Unternehmensgruppe wir haben. Über 100 Developer da drauf und
dann wird jeden Tag einer random mäßig ausgewählt und der muss
diesen 15 Minuten Test machen und normalerweise sind das Leute
die jetzt nicht aus dem Team diese Plattform bauen oder diese
Dokumentation schreiben und in Zukunft werden wir dann
natürlich auch immer schauen ob wir vielleicht irgendwie
Freelancer oder Menschen aus der Community finden oder wir
veranstalten auch regelmäßig auf Konferenzen einen Hackathon oder
sowas und schauen dann ob, also daran müssen wir uns irgendwie
messen lassen, ist die Dokumentation so gut wie.
Dass du das erste Erfolgserlebnis halt auch
irgendwie schnell hast. Ich glaube, das ist auch Teil
davon. Eine Dokumentation muss Spaß
machen, das war zum Beispiel so eine der Sachen, weswegen ich
mich so an sowas wie Stripe oder Zero erinnere, weil ich finde,
das macht dann Spaß damit zu arbeiten und Spaß kommt ja oft
auch durch Erfolgserlebnisse. Ja, und ich meine, Ihr seid
jetzt auf der Reise die beste developer Doku auf diesem
Planeten zu bauen und du hast aber gerade schon Stripe und Ort
Zero genannt, die wirklich weit vorne sind und die uns beiden
glaube ich als positive Beispiele in Erinnerung
geblieben sind. Weil wir beide schon mit diesen
APIS auch mal in der Vergangenheit gearbeitet haben.
Und von daher ist es, glaube ich, ganz interessant, so ein
bisschen ein paar Dinge herauszugreifen, die die beiden
besonders gut machen. Und eine Sache, die bei Stripe
auffällt, ist, dass wir tatsächlich irgendwie so einen
Split in der Navigation haben beziehungsweise im UI.
Das heißt, wir sehen halt sowohl den Code als auch die
Dokumentation nebeneinander und den Code selber.
Die verschiedenen Samples sehe ich in unterschiedlichen
Programmiersprachen, das finde ich persönlich super wichtig,
weil irgendwie man will auf den ersten Blick verstehen, wie
funktioniert das, eine bestimmte API zu nutzen und das möchte ich
natürlich in der Sprache oder kann das am besten in.
Mit der Sprache verstehen, in der auch mein Projekt ist, in
der ich geschult bin. Und wenn ich jetzt jedes Mal
quasi im Kopf erstmal so umdenken muss.
Das Beispiel ist jetzt irgendwie in Python, aber ich selber mache
irgendwie C Sharp oder was völlig anderes, dann macht das
natürlich für mich erstmal die Sache komplizierter.
Hey, du fühlst dich irgendwie nicht so richtig abgeholt.
Immer finde ich. Also du denkst dann schon, ah,
wenn die schon die Doku nicht in der Sprache haben, dann hat das
Framework oder was auch immer ich mir den jetzt anschaue, ja
wahrscheinlich auch kein First. Class Support für den Stack, auf
dem ich mich da wohlfühle und das war schon so ein bisschen
auch eine Diskussion bei uns. Welche Sprachen unterstützen
wir, was sind denn noch so die gängigsten Sprachen, in der ich
sag jetzt mal e Commerce Welt, also was bei uns relativ früh
sehr weit oben stand ist ein php SDK.
Was ja wahrscheinlich das erste Mal so bei den meisten nicht an
allererster Stelle stellen würde.
Aber was einfach sehr viele in unserer Branche noch betrifft,
zum A also a weil es da auch einfach viele Shop Lösungen
einfach gibt, die schon auf PHP basieren, so ein bisschen auch
in die Jahre gekommen ist, dann ganz viel WORDPRESS hat ja auch
so ein shopping Ding, da passiert alles auf PHP und mit
La Ravelle hat es ja auch wieder so ein bisschen so einen
Aufstieg erlebt und man muss halt schon überlegen welche
Sprachen hast du da und man muss auch sagen.
Ich finde so Mehrsprachigkeit heute auch kein nice to have
mehr, zumindest was die Programmiersprachen angeht.
Denn wenn er jetzt nur eine Sprache da anzeigt, muss sich ja
auch Bewusstsein, dass man 80% der Developer nicht in ihrer
Muttersprache abholt und das finde ich witzig, weil ich finde
das deutlich wichtiger als verschiedene wirkliche Sprachen,
also Deutsch, Englisch, französisch, chinesisch, was
weiß ich anzubieten, da würde ich, da würde ich sogar sagen,
da braucht es die Mehrsprachigkeit gar nicht, bin
ich zum Beispiel kein Freund von der Dokumentation in.
Ganz vielen verschiedenen Sprachen zu machen, unter
anderem, weil das dann oft über automatische Übersetzungen
gelöst wird. Das finde ich oft frustrierend,
weil es eine schlechte Qualität hat und sonst nicht wirklich
wirtschaftlich lösbar ist. Dass du wirklich Leute hast, die
das richtig runterschreiben verschiedene Sprachen, dann ist
das Problem, was ist denn, wenn die Übersetzungen sich irgendwie
widersprüchlich sind und ich kenne das so ein bisschen von
der Microsoft Dokumentation, die ist ganz ganz wild übersetzt,
also da stehen dann wirklich ganz komische Sachen in Deutsch
und. Man klickt man manchmal
irgendwie einen Link an und dann ist das entweder in Deutsch,
weil der Browser auf Deutsch ist, oder in einer ganz
komischen Sprache, weil das noch Teil der URL dann irgendwie war.
Und das erste was man da immer sucht, ist sofort.
Wie stelle ich das auf Englisch rum, weil ich weiß das ist so
die Source of Truth und das finde ich schon spannend, dass
eigentlich in unserer Developer Welt ist Mehrsprachigkeit
wichtig, ist aber eher im Sinne von Programmiersprachen, dass es
eher wichtig ist, die sag ich mal native Programmiersprache.
Von einer Benutzerin oder einem Benutzer abzuholen, als die
native Muttersprache, da würde ich heute so weit gehen und
sagen, das kann doch erst mal alles in Englisch sein.
Ja, wobei wir vielleicht auch sehr gut im Englischen sind und
gerade in Deutschland oder im europäischen Raum, das durchaus
eine sehr vertraute Sprache ist. Es mag dann auch vielleicht
andere Märkte geben, wo das nicht so ist.
Ich glaube, wenn du jetzt irgendwie eine.
In den japanischen Markt eintritt kann glaube ich auch
schon eine japanischsprachige Dokumentation sinnvoll sein,
sofern sie denn gut ist, weil ich glaube, eine schlechte Doku
hilft dann auch nicht weiter und da muss man natürlich auch in
professionelle Ressourcen investieren, die deine Ki
Übersetzung dann noch mal reviewen und sagen, macht das
alles Sinn, hört sich das natürlich an.
Und aber ansonsten bin ich dabei.
Dir ist es wichtiger, glaube ich, die verschiedenen
Programmiersprachen zu haben, auch wenn man sagt, ich habe ja
eine Rest API und dieses Code Sample ist ja nur ein Beispiel,
am Ende weiß ja jeder, wie er eine API anspricht, ist es
glaube ich um die Leute abzuholen sehr wichtig und ich
glaube, um die Leute abzuholen, ist es auch sehr wichtig, dass
du nicht einfach nur Code hast, der irgendwie so spoilerplate
Code ist, sondern auf dich angepasst ist.
Und das machen ja auch. Sowohl auf Zero als auch als
auch Stripe. Sehr gut, dass wenn du dort
eingeloggt bist, dann bist du quasi auch gegen die API schon
authentifiziert. Du hast quasi deinen API Key
dort hinterlegt und kannst auch direkt die Sachen ausprobieren
und testen und von daher hast du so eine personalisierte
Dokumentation und hast halt nicht noch die Herausforderung.
Ich muss irgendwo einen Testdaten hinterlegen, sondern
du kannst tatsächlich direkt mit den Informationen.
Die du bei deiner Registrierung angelegt hast.
Sofort arbeiten. Ja, ultra geil eigentlich.
Das ist, wieso ein eingebauter Postman dann eigentlich also so
eine interaktive Dokumentation, das ist fast schon, das ist
jetzt auch ehrlich gesagt bei uns erstmal ein stretch Goal.
Also fände ich auch cool, aber wir müssen überhaupt erstmal ein
sehr, sehr cooles Grundgerüst schreiben, aber finde ich auch
mega geil, wenn man halt eingeloggt ist und dann
irgendwie alles schon funktioniert und du auch Daten
aus deinem Tendent halt zurück kriegst in diesen Samples, was
Stripe auch noch ultra cool macht und.
Und das ist gar nicht so so sehr Teil der Dokumentation.
Aber das ist natürlich damit verbunden ist, dass die bei fast
jeder Fehlermeldung, die sie dir rausgeben, die erwartbar ist,
also im Sinne von da hat Stripe darauf vorbereitet, dass diese
Fehlermeldung passieren kann in fast jeder Fehlermeldung ist ein
Link zur Doku enthalten, wo sie dir diesen Fehler erklären oder
zumindest wo du eine Stelle nachlesen kannst, die mit dem
Fehler zu tun hat, wo sie dir ein Konzept erklären, ob.
Oft kann es ja irgendwie sein. Also wenn du jetzt irgendwie
eine falsche input Format hast, dann verlinken sie dich direkt
dazu, wo das richtige input Format beschrieben wird oder
wenn du einen logischen Fehler gemacht hast, weil du vielleicht
den einen Endpunkt gecallt hast, den du gar nicht callen
solltest, bevor du nicht den anderen Callst.
Da ist es ja wirklich Teil davon, also das muss man sich ja
dann überlegen, wie kommt das zustande, da geht ein, da muss
das developer Team was diesen Service baut auch die Doku die
für die für die Endkunden die Developer sind dann sehr gut
kennen und du musst ja sehr eng verbunden sein, dass man sagt
EY. In diesem Fehlerfall müssen wir
einen Absprungpunkt zur Doku haben und das heißt, als
Developer klickst du dann einfach, weil du diese Meldung
von der API vielleicht zurückbekommst direkt in diesen
Link springst. Zum richtigen Punkt der Doku und
das ist natürlich auch eine super coole Experience ist.
Mir tatsächlich letzte Woche auch in unserer Github Doku
aufgefallen, dass wir das machen.
Vielleicht nicht auf dem Level, dass man wirklich für jeden
Fehlercode eine spezielle Erklärung bekommt, aber da
kriegt man tatsächlich auch einen Hinweis.
Hey, geh bitte auf den Doku Link, deswegen kriegst du hier
verbindend zurück, weil du hast den falschen Access Token
genommen, hier ist erklärt was du stattdessen machen musst.
Also fand ich super gut um richtig schnell auf die Lösung
des Problems zu kommen und was bei Odds Theory ja auch cool
ist, ist, dass sie. In dieser Live View, in der du
arbeitest direkt halt bestimmte Variablen für dich ersetzen,
weil manchmal ist es ja so ein bisschen obskur.
Was meinen die Developer letzten Endes damit, wo finde ich jetzt
diese Information in meinem Portal, um die dann raus zu
kopieren und dann die einzelnen Felder auszufüllen und wenn das
alles von voraus gefüllt ist, lerne ich natürlich auch viel
schneller, wie ich mit dieser API arbeite und was sich hinter
bestimmten Variablen eigentlich verbirgt.
Ja, du kannst Duples natürlich einfach copy, pasten und
irgendwo verwenden, ohne dass du jetzt noch mal Großes anpassen
musst. Und.
Secrets vielleicht schon, aber das finde ich eher, dass es auch
Zero das extrem gut macht. Die haben ja auch diesen diesen
interaktiven, wie soll man sagen, sowieso ein quickstar
Generator eigentlich. Also du kannst wirklich genau
deinen Stack zusammenklicken und auch so ein bisschen die
Features die du brauchst und bekommst dann wieso eine
maßgeschneiderte Anleitung und könntest theoretisch auch zum
Beispiel einfach ein Sample oder so ein Template runterladen, das
können wir auch überlegen, wenn meine Challenge ist die 15
Minuten. Da kann ich dich ja fragen.
Ey malte, was ist denn deine Lieblingsprämiersprache, welches
von diesem Plattform Feature willst du denn eigentlich
benutzen? Hostest du in einem Docker
Container oder vielleicht direkt auf Ada Bul US und Azure oder
hast du irgendwie hetzner oder versell oder was auch immer und
dann kannst du eine zip Datei runterladen wo eigentlich alles
schon drin ist und du musst nur einfach einmal deployen oder
musst einfach vielleicht so ein Script schon drin für Deployen
oder was auch immer und. Und ich zwinge dich ja
eigentlich dann dazu, keine Fehler zu machen.
Dann kannst du dir den Code in Ruhe noch mal angucken oder
vielleicht führt das Tutorial dich dann nach deinem ersten
Deploy mit Erfolgserlebnis dann durch und sagt Ey okay, jetzt
gucken wir mal, was hast denn du da eigentlich deployed?
Lass uns jetzt mal den Code aufmachen und so und ich finde
da sieht man schon so einen gemeinsamen Nenner, also beide
Beispiele die wir jetzt getroffen haben treffen also die
wir jetzt genannt haben treffen Entwickler ja eigentlich ganz.
Genau da, wo sie gerade arbeiten, wo sie sich irgendwie
beheimatet fühlen, versuchen Reibungen auf so ein absolutes
Minimum zu reduzieren. Aber man merkt, glaube ich,
auch, das ist schon ganz schön viel Arbeit da, irgendwie dann
für jeden Text Tag irgendwas zu bauen oder diese ganzen Samples
vorzubereiten, oder vielleicht ist noch ein Generator dahinter,
also es ist nicht ein ich schreibe eine markton Datei
runter und dann ist gut, sondern man merkt schon, eigentlich ist
Dokumentation und das ist dann auch so ein bisschen der
Schluss, zu dem wir später gekommen sind.
Eigentlich Dokumentation ein Produkt von dir oder zumindest
ein Nebenprodukt und das ist auch der Grund, warum kann ich
ja schon mal vorgreifen, unsere Kick ass Developer Dokumentation
jetzt auch einen Produktmanager hat, der dafür verantwortlich
ist. Ja, und ich glaube, gerade bei
dieser Rolle oder bei wem auch immer die Verantwortung für die
Dokumentation liegt, muss halt auch das Verständnis für.
Die Arbeit eines Developers Dasein man muss verstehen
irgendwie. Wie denken Developer, wonach
suchen sie und wie muss ich Sie abholen, also mit welchem
Hintergrundwissen kommen Sie zu mir, welche Informationen muss
ich liefern, damit sie möglichst schnell produktiv werden und
dementsprechend merkt man natürlich auch so ein bisschen,
wenn eine Dokumentation entweder selber von Developerern
geschrieben wurde oder zumindest von Leuten, die tagtäglich
selber mit Software developerern arbeiten, die genau wissen.
Welche Informationen muss ich liefern und welche sind
vielleicht auch überflüssig, weil manchmal sind solche
Dokumentationen auch total the Bose und ganz viel Text und du
denkst auch, das will ich eigentlich gar nicht wissen, gib
mir die Code Samples und dann kann ich sofort loslegen und ich
glaube dieses Verständnis und Gefühl dafür ist extrem wichtig
um hier eine hohe Qualität zu erreichen.
Ja, glaube ich auch. Das ist auch irgendwie
sympathisch, wenn du so merkst, ach guck mal, das haben auch
Nerds gemacht. Ja, lass uns doch mal
reingucken. Also was, was würdest du denn
sagen, was was gehört denn jetzt rein in so eine Dokumentation?
Jetzt haben wir schon viel gesprochen, was macht eine
Dokumentation Kick ass aber am Ende am Ende des Tages brauchen
wir ja den Content was wenn du warst ja wahrscheinlich jetzt ne
ich habe dich ja ehrlich gesagt ein bisschen überrumpelt auch
mit dem Thema muss man auch ehrlicherweise dazu sagen,
bisschen spontan diese Folge aufgenommen haben ich bin jetzt
voll drin im Thema, deswegen interessiert mich eben umso mehr
was. Was würde dir denn jetzt so
spontan in den Kopf kommen, wenn du jetzt sagen, wenn du jetzt
runterschreiben müsstest, so eine Struktur oder zumindest auf
der linken Seite die Navigation? Was gehört denn für dich an
Inhalt in eine gute Dokumentation?
Du hast ja gerade so Code Samples genannt, aber.
Das reicht ja nicht. Ich kann ja nicht nur kurz zur
Verfügung stellen. Ich glaube, zusätzlich so ein
bisschen so ein Getting Started Guide irgendwie die einfachsten
Beispiele einmal durchgeführt, damit man irgendwie reinkommt in
die ganze Nomenklatur. Also welche Begriffe gibt es,
was, wo sie wissen, um nachher die ganzen anderen API s auch
nutzen und verstehen zu können. Und dann halt für übliche Use
Cases, vielleicht auch kurze Quickstar Tutorials, die mich
dann so ein bisschen einführen. Und wenn ich das dann
durchlaufen habe, komme ich halt auf diese allgemeine
Dokumentation, wo halt einfach alle AP is dokumentiert sind für
die ganzen Use Cases in wie gesagt den unterschiedlichen
Sprachen mit Beispielen und wie wir gerade schon gesagt haben im
Gold Standard möglichst interaktiv, sodass ich entweder
die Sachen direkt auf der Seite ausprobieren kann oder
zumindest. Ganz schnell Copy pasten kann,
was ich zum Beispiel super praktisch finde, ist, wenn dann
einfach irgendwie auch so eine Copy paste Möglichkeit ist um
einfach irgendwie so einen Curl für eine Rest API rüber zu
kopieren. Einfach aufs Terminal.
Ich kann es sofort ausführen, gucken was da zurückkommt finde
ich total praktisch, also quasi so ein bisschen in mehreren
Stufen aufgebaut um die Leute halt da abzuholen und wer sagt
okay ich kenne. Ich kenne mich grob mit der
Technologie schon aus. Kann man vielleicht diesen
ersten Guide irgendwie skippen und direkt in die Tutorials
reingehen, aber so grob von der Struktur würde ich vorgehen,
ohne jetzt im Detail mich damit beschäftigt zu haben, aber ich
glaube, du hast dich tatsächlich auch schon so ein bisschen auch
mit dem so akademischen Hintergrund da beschäftigt, was
man da machen sollte. Ja, akademisch ist wie gesagt,
aber da gibt es natürlich auch, wie für alles in der
Softwareentwicklung so. Frameworks und irgendwelche
Weisheiten es gibt so dieses Diattaxis Framework, das ist so
eine Orientierung, da gibt es so, also das ist eigentlich so
eine Denk und Arbeitsweise im Bereich von Dokumentationen, da
gibt es halt irgendwie so das unterteilt Doku eigentlich auch
in so 4 Sachen, die du auch gerade schon eigentlich so ein
bisschen genannt hast. Also in in Tutorials, in
Anleitungen sag ich gleich noch mal, was da der Unterschied ist
in technische Referenzen und. Und dann noch mal ganz genaue,
tiefere Erklärungen. Und das finde ich schon
interessant, dass du auch gesagt hast, so eigentlich müsstest du
mit so einem Quickstart Guide oder sowas anfangen, da haben
auch viele bei uns irgendwie plädiert, das fand ich auch
sinnvoll. Also du würdest auch sagen, man
steigt ein mit einem Hey, du bist das erste Mal hier, ich
führe, also du würdest auch mitgehen mit diesem, ich führe
dich jetzt in 15 Minuten zum Erfolg und danach erkläre ich
dir erst ganz genau okay was sind denn überhaupt hier die
Konzepte der Plattform und und so weiter da würde.
Würdest du das so rummachen oder würdest du, weil ich habe immer
das Gefühl, wenn man erst zu viel lesen lesen muss, weil das
ja eben auch diese Wahl of Text irgendwie referenziert, dann ist
es auch so ein bisschen demotiviert oder man scrollt da
eh drüber, weil ich erwische mich auch dabei, dass ich
manchmal einfach so scroll, es scroll, es scroll und sage, wo
kommt jetzt das erste Codebeispiel ja.
Ich glaube, es ist wichtig, den Leuten auch möglichst früh ein
Erfolgserlebnis zu geben. Und wenn du dann irgendwie in 15
Minuten zu einem laufenden Sample kommst.
Es fühlt sich immer schon gut an.
Und wenn man in dem Zuge dann noch vielleicht so ein bisschen
die ganzen grundsätzlichen Konzepte kennenlernt, dann
funktioniert das natürlich super.
Ich glaube, niemand will heute noch irgendwie umfangreiche Doku
Texte lesen, also ich glaube, man macht das immer dann im
Zweifelsfall, wenn irgendwas nicht funktioniert und man
rausfinden will, warum funktioniert es nicht, dann geht
man noch mal ins Detail rein und sagt irgendwas muss ich da wohl
überlesen haben, als ich einfach nur den Code kopiert habe, aber.
Aber ich glaube, am Anfang braucht man das nicht und dann
sollte man eher sich darauf konzentrieren, einfach einen
lauffähigen Prototypen einfach den Leuten an die Hand zu geben.
Das ist auch so ein bisschen wie dieses, die Attaxis Framework
dann irgendwie vorgeht. Also wenn das passiert oder auch
mal eine Doku schreiben will, das verlinken wir natürlich und
das versucht so ein bisschen irgendwie zu beschreiben, was
ich schreibe, wie ich es schreibe und wie ich es
organisiere, und die sagen auch so, das geht so ein bisschen
vom. Von Action First und dann später
irgendwie dieses Understanding, also die sagen Tutorials, da
lerne ich was, da lerne ich wirklich Ende zu Ende, wie
funktioniert irgendwas auf der Plattform, dann gibt es diese
Anleitungen, da hast du glaube ich eben how to Guides oder
sowas gesagt, die sind so ein bisschen zielorientierter, also
wirklich ganz konkret, wie mache ich x auf der Plattform, da wird
dann nicht mehr so viel erklärt, sondern wirklich wie komme ich
zu diesem Ziel, wie binde ich jetzt das Login ein und.
Und da gibt es weiter unten neben diese Erklärungen und
Referenzen. Also das ist dann eher, dass man
versteht, wie eigentlich die Plattform funktioniert, oder
Referenzen können auch irgendwie so Beispiel Implementierungen
sein und kriegt dann halt da irgendwie mehr Informationen
raus, die sind dann. Ja, so eine Referenz ist eher
informationsorientiert und so ein How to Guide ist dann
irgendwie eher zielorientiert und am Ende brauchst du glaube
ich diesen Mix, aber ich würde mich schon, außer man startet so
ein Erfolgserlebnis führt dann so ein bisschen ein.
Worum geht es denn eigentlich hier in der Plattform und ich
mag es auch immer, wenn man so ein bisschen so einen Guide hat
oder auf der zweiten Seite dann wie navigiere ich denn
eigentlich durch diese Dokumentation, wo finde ich denn
eigentlich, was muss natürlich auch konsistent sein und.
Und dann irgendwo natürlich auch die Konzepte erklärt zu haben.
Was steckt eigentlich hinter den Begrifflichkeiten und ich
glaube, das ist, was gerade dieses erklären von Konzepten,
das wird oft vergessen, das halte ich aber für elementar
wichtig, also dieses oft heißt es so wie Concepts oder
Terminology und alle springen natürlich immer direkt zu diesem
Get It Started Guide, aber wenn der Entwickler gar nicht
versteht, was ist denn überhaupt ein Tendent in Deinem, in deinem
Kontext oder ein Scope, oder die reden ja die ganze Zeit von
einer App Shell. Aber was ist denn eine App Shell
dann? Dann fühlt es zwar so an, als
bräuchte ich das alles nicht wissen, aber als Developer laufe
laufe ich da oft nach 5 Minuten vor eine Wand und weiß dann gar
nicht und verstehe dann nicht, warum ich hier nicht weiterkomme
und das ist ja auch so ein bisschen eine Übung für das
eigene Team, das da mal aufzuschreiben, denn wenn ich
jetzt mir irgendwie so. Es gibt ja irgendwie diese You
Biquitis Language, die kommt so ein bisschen aus dem Domain
driven Design und da muss man sich auch auf eine gemeinsame
teamübergreifende Sprache einigen, die sowohl der Sales
als auch das Engineering als auch der Support spricht.
Und ich glaube, wenn man das runter schreibt und auch dem
Kunden so ein bisschen in der Dokumentation dann mitgibt und
sich da auch immer wieder drauf referenzieren kann, dann hilft
das schon und allein das Mal aufzuschreiben ist bestimmt auch
für das ganze Unternehmen wertvoll.
Und jetzt haben wir so ein bisschen die Inhalte
zusammengefasst. Aber jetzt vielleicht noch mal
zu der Dokumentation als Produkt, welches bestimmte
Features hat. Also wenn ich jetzt das ganze
technisch implementiere, wir hatten gerade so ein bisschen
über den Goldstandard gesprochen, wo du irgendwas
direkt auf der Webseite ausprobieren kannst.
Etwas vorausgefülltes du bist eingeloggt, was würdest du jetzt
sagen, braucht man heutzutage um Leute wirklich abzuholen?
Dark Mode. Den solltet ihr natürlich sofort
vom Browser übernehmen beziehungsweise vom
Betriebssystem von daher. Hoffentlich muss man sich da
nicht mehr groß drum kümmern. Das stimmt, aber ich gehe jetzt
mal davon aus. Also deine Frage ist ja erst in
Richtung welche, für welche Dokumentationsplattformen oder
Technologie entscheide ich mich jetzt und da können gar nicht
alle Dark Mode, aber die modernsten natürlich schon.
Ja, ich glaube, es gibt so ein paar heiße Kandidaten.
Es gibt irgendwie, es gibt so dieses Dokusaurus von von
Facebook, ist, glaube ich, begründet, irgendwie als Open
Source Plattform und ganz viele Bezahlplattformen gibt es
irgendwie auch, und wenn wir an dem Punkt sind, wo ich sage okay
gute Inhalte reichen nicht nur, sondern ich muss auch eine
coole, coole Plattform bereitstellen, dann klar, ich
glaube wirklich das absolute End Goal ist das, was du eben gesagt
hast mit diesem interaktiven API Playground.
Ich glaube, wenn ich Dinge direkt im Browser ausprobieren
kann ohne Setup. Das haben die meisten auch
einfach nicht. Da trennt sich glaube ich
wirklich die Scheu vom Walzen, vom Walzen.
Das ist wahrscheinlich aber auch am krassesten zu implementieren.
Es gibt aber natürlich auch so ein paar Convenience Features,
wo ich sage, ohne ohne die komme ich nicht mehr aus und zum
Beispiel, was ich elementar wichtig halte für elementar
wichtig halte, ist zum Beispiel Versionierung.
Ich finde es total frustrierend, wenn nur die aktuellste Version
des Produktes Versioniert ist, weil das einfach für Enterprise
Kunden vor allem nicht realitäts.
Nah ist und welche Version der der API die dokumentierte sehe
ich denn jetzt hier gerade? Also irgendwie so ein Version
selector irgendwo oben, das ist glaube ich schon Standard, weil
das ist ja sonst so einfach frustrierend, ich muss ja nicht
für jeden Patch release eine eigene API rausgeben, aber
zumindest mal für jede Major Version und je nachdem ob ich
halt auch irgendwie minor versions noch irgendwie mit
dokumentieren will oder muss oder sowas.
Finde ich es schon auch ein gutes Gefühl zu sagen, ah guck
mal, ich nutze Version 134 von dem Produkt, also stelle ich
zumindest auch mal die API oben rechts.
Ist ja oft so ein Version dropdown auf die Version 12.
Ja und dann das andere, was wir vorhin ja schon erwähnt hatten,
ist so ein bisschen eine Personalisierung, also wenn ich
eingeloggt bin, dann sollte jetzt nicht die Dokumentation
auf einem separaten URL sein, wo mein Login nicht funktioniert,
sondern ich sollte, wenn ich im Developer Portal angemeldet bin,
auch dort angemeldet sein und dann im Idealfall kriege ich
dann Informationen zu. Vorausgefüllt damit die
Dokumentation personalisiert ist.
Das heißt, ich habe vielleicht so einen developer API Key, der
direkt in den Code Samples angezeigt wird und kann das dann
direkt ausprobieren und du hast gerade gesagt, so der Gold
Standard ist so dieses interaktive API Playground den
ich direkt auf der Seite habe, aber alternativ könnte man
natürlich auch hingehen und irgendwie einen.
Eine Postman Umgebung für die Developer bereitstellen, die
sich herunterladen können und dann kann ich das direkt öffnen
und kann direkt mit der API arbeiten.
Also irgendwie etwas was mir es ermöglicht ermöglicht ganz
schnell interaktiv mit der Plattform zu arbeiten.
Genau. Was auch trivial klingt, aber
elementar wichtig ist, ist eine. Gute Suche finde ich mit einem
auch mit einem guten Indexing, vielleicht sogar mit irgendwie
einem Embedding. Vielleicht so ein bisschen KI
drin, dass wenn ich jetzt irgendwie nach weiß ich nicht
login suche, trotzdem auch die Seite wo Authentication
draufsteht, finde, weil es thematisch einfach irgendwie
zusammenhängt und auch hier, wir haben jetzt bei euch auch eine
Plattform gesucht, die Search Analytics anbietet, das heißt
die mir sagt. Ey, wonach suchen denn Leute auf
deiner Dokumentation und finden vielleicht nichts oder finden
schlechte Ergebnisse? Oder wenn du es mit KI machst
auch Ergebnisse im schlechten Ranking, also dass du selber
diesen Content Gap eigentlich analysieren kannst und das dann
direkt wieder produktfeedback, nämlich zu dem Produkt Developer
Dokumentation ist, das ist ja ultra wertvoll, dass du da
gehört, nicht nur eine Suche mit diesem Indexing und diesem
diesen Product Gaps hinzu und diesen Search Analytics.
Sondern eigentlich brauchst du Analytics auf der gesamten
Developer Dokumentation. Was sind Knickpfade, die ins
Leere führen, was sind Seiten, die Leute irgendwie erstaunlich
häufig wieder und wieder und wieder aufrufen?
Das gibt dir ja dadurch, dass deine Developer Dokumentation
oder die Erste die erste Anlaufstelle ist, vor allem wenn
irgendwas nicht funktioniert oder unklar ist, gibt dir das ja
auch wahnsinnig viel Info über dein Produkt eigentlich oder
zumindest die developer Seite deines Produktes, wie Leute mit
deiner Dokumentation interagieren.
Ich glaube theoretisch, solange die Leute immer noch über Google
suchen, kann ich natürlich auch da schauen.
Suchen die halt nach meiner Plattform und Web Hooks und
finden jeweils nichts. Aber wenn ich das natürlich in
meinen Docs habe, kann ich auch die integrierte Suche dafür
verwenden und. Und du hattest es gerade so
beiläufig erwähnt, und das ist jetzt im Moment so ein bisschen
das Thema. Man muss KI haben, brauche ich
tatsächlich vielleicht auch so einen interaktiven AI Mode, wo
ich als Developer nicht suche nach etwas, sondern wo ich eine
Frage stelle und bekomme dann. Basierend auf diesem Drag
Indexing, was du gerade erwähnt hattest, oder der Dokumentation
direkt eine Antwort. Also ich schreibe einfach nur,
wie mache ich folgendes und dann kriege ich sofort mein Code
Samples zurück, statt lange auf der Seite zu suchen oder ist das
noch nicht Standard oder braucht man das gar nicht, weil
eigentlich arbeiten alle Leute ohnehin mit.
Ihrem AI Developer Agent der Wahl und meinem Chat Fenster,
was ich dann vielleicht auf der Webseite hätte, würde eh niemand
benutzen. Ja das.
Ist spannend. Du hast jetzt gerade schon
irgendwie die Antwort gesagt, die ich eigentlich auch hätte
sagen wollen und es ist deswegen spannend, weil diese ganzen
Plattformen, die wir jetzt evaluiert haben und die wir uns
angeschaut haben, die versuchen dir das natürlich irgendwie als
cooles Feature mitzuverkaufen also die sagen, ey, du hast dann
hier direkt hier. In der Dokumentation, die wir
für dich hosten, so einen Dokum, so einen Developer Support Agent
und dem kannst du dann da unten Fragen stellen und so und dain
oder ist natürlich und dann musst du natürlich auch Münzen
einwerfen, damit der entsprechend viele Tokens hat,
damit deine Developer auch die Fragen stellen können und er
nicht irgendwie irgendwann verstummt, wenn du da nicht
genug Geld reingeschmissen hast und ich habe da eigentlich auch
direkt so eine Anti Meinung zu gehabt und bin auch dann zu dem
Punkt gekommen, den du gerade gesagt hast.
Ich möchte glaube ich schon dafür sorgen, dass meine
Dokumentation gut von KI verarbeitet werden kann, im
Sinne von, dass die Maschinen lesbar ist für ll MS.
Aber eigentlich will ich ja, dass mein Coding Agent gut mit
dieser Dokumentation klar kommt. Also wenn ich denke da so an
Shat CN zum Beispiel als Ultra populäres UI Framework irgendwie
gerade da. Die haben zum Beispiel den
SCHÄTZ CN MCP Server, und den bringe ich dann mit und der weiß
auch vielleicht Dinge, die gar nicht in Dokumentation stehen
über schätz, CN und der weiß genau, wie man neues Projekt
aufsetzt und der unterstützt dann eigentlich meine KI mit dem
richtigen. Kontext dafür, wenn ich schätz,
Sie nutze. Und brauche ich dann jetzt für
meine eigene Dokumentation dann einen eigenen MCP Server?
Weil das ist so ein bisschen overkill, weil vielleicht
developer irgendwie mit unterschiedlichsten Plattformen
arbeiten und die wollen ja nicht für jeden einen eigenen MCP
installieren, oder reicht es, wenn ich meine Webseite so
gestalte, dass irgendwas wie context 7 oder andere
Technologien meine Dokumentation möglichst gut einlesen können?
Ja, also wir werden jetzt keinen MCP Server für unsere Doku
bauen, es sei denn, die Plattform, für die wir uns
entschieden haben, bitte das einfach als fertiges Produkt an,
dann würde ich drüber nachdenken.
Ich glaube aber sowas wie eine Context 7 Integration habe ich
schon mal gemacht, wem context 7 gar nichts sagt, hört mal in die
MCP Folge rein, da haben wir so ein paar coole MCP Server für
die Valopper auch erwähnt und context 7 ist halt einer davon,
da kann ich eben ja meinen KI Agent durch Dokumentation
anreichern. Ja, ich würde sagen sowas reicht
und so eine LMS. Txt, also das ist das ist ja
eigentlich sowas wie ja eigentlich so.
Also eigentlich finde ich so eine native Dokumentation schon
eigentlich gerade so den spannendsten Trend und so eine
lm. Txt ist eigentlich so das
Pendant zu früher mal so einer Robots.
Txt und erlaubt dann eben LMS und AI Coding Assistenten, meine
Docs ich sag mal korrekt zu konsumieren und das glaube ich
muss ich heute schon machen das. Dabei würde ich es jetzt aber
glaube ich erstmal belassen. Aber ich glaube, das muss man
auch so ein bisschen im Hinterkopf haben, dass so ein KI
System irgendwie so ein Coding Agent könnte natürlich auch
einfach meine Webseite lesen, aber damit liest er natürlich
furchtbar viele Tokens ein, die man am Ende gar nicht braucht.
Dieses ganze Ui Thema, was ich natürlich für menschliche
Developer habe, dass es gut aussieht, das ist gut
formatiertes und natürlich vielleicht die ganze sehr
verbose, natürlich sprachlich und.
Dokumentation ist vielleicht gar nicht so relevant und dann
kriege ich das in dieser LMS Datei sehr komprimiert und kann
natürlich da auch am Ende den Developer helfen, hier auch
Tokens zu sparen. Was ich allerdings schon
spannend finde, aus so einer KI Perspektive ist das Thema, Wir
haben sie jetzt mal genannt, Custom Instructions fürs Vipe
Coding. Wir haben uns bei der Planung
unserer Developer Dokumentation hingesetzt und so verschiedene
Personas identifiziert und dokumentiert und gesagt okay wer
benutzt denn eigentlich unsere Plattform?
Da sind die absoluten Coding Experten dabei, da sind die
Händlerinnen und Händler dabei, die vielleicht irgendwie sich
selber irgendwie eine Extension bauen wollen.
Da sind unsere langjährigen Partner dabei, die in ihrer
Technologie absolute Profis sind, aber noch nicht auf
unserer Plattform. Und relativ schnell kam drauf.
Da sind aber auch jetzt so eine ganz neue Generation von
Developern dabei und die haben dann erstmal so Vipe Coder
genannt, also wie muss ich meinen Cloud Code konfigurieren
um für eure Plattform eine erfolgreich eine App zu bauen
und das heißt wir haben schon so eine Section, die wir auch vipe
Coding wahrscheinlich nennen werden.
Wo ich dann halt so, ja sag ich mal Custom Instructions oder
gute Proms oder MCP Server die gut funktionieren oder
vielleicht auch irgendwie halt irgendwas wo wir wir werden ja
auf jeden Fall auch Leute dran setzen, die noch nie vorher
programmiert haben, die müssen auch in 15 Minuten irgendwie so
eine App bauen können, die werden wahrscheinlich irgendwie
eine KI verwenden und den werden wir ganz ganz eng über die
Schulter schauen zu schauen, was hat denn da zum Erfolg geführt,
dass sich quasi Leute, denen der Code total egal ist.
Zumindest aber dabei helfen kann, mit Vibe Coding ein gutes
Ergebnis zu erzielen, weil ich eben ihnen gesagt habe, was sie
ihrer KI sagen müssen, damit die überhaupt auf die Idee kommt,
unsere Docs zu lesen und was man da vielleicht für Custom
Instructions irgendwo mit eintragen kann.
Und da freue ich mich schon sehr darauf, irgendwie diese Sektion
zu schreiben, weil das ist ja auch ein.
Ja, über diesen Wettbewerbsvorteil, den du haben
kannst, wenn ich sagen kann, für meine Plattform kann jede und
jeder Apps bauen, unabhängig davon, ob es Entwicklerinnen
oder Entwickler sind. Und du sagst das jetzt gerade so
beiläufig. Ich freue mich darauf, diese
Sektion zu schreiben, aber wer schreibt jetzt die Docs am Ende?
Das machst ja nicht du, sondern das machen ja Leute, die sich
damit auskennen. Ja, das ist halt die Frage.
Wer kennt sich damit aus? Also die Frage haben wir uns
natürlich auch gestellt und. Das erste, was irgendwie im Raum
steht, ist so. Jeder sagt Ja, das müssen die
Entwicklerinnen und Entwickler schreiben.
Das finden die bestimmt gut. Genau das finde ich bestimmt
gut, die können das bestimmt auch gut, weil die finden ja
die, die schreiben ja schon technische Dokumentationen so
wahnsinnig gerne. Und jetzt, wenn Ironie da jetzt
mal ausblendet, Entwickler wissen alles, aber schreiben
natürlich wahnsinnig ungern und die Alternative dazu ist, es
gibt ja auch so, wenn. So Technical Writer, also wieso
Autorinnen und Autoren die schreiben gut, die wissen aber
nicht alles, die verstehen das Produkt ja nicht in der Tiefe,
vor allem sind die oft auch irgendwie auf Freelancer Basis
unterwegs und die kann man heiern und ja, dieses Problem
habe ich natürlich, wenn eine KI jetzt irgendwie meine
Dokumentation schreibt, die kann halbwegs gut und smooth mir dann
irgendwie was runterschreiben, aber die versteht ja auch mein
Produkt nicht. Mühle befinden wir uns natürlich
auch. Das bedeutet, ihr habt jetzt so
ein bisschen. Die 2 Varianten zur Auswahl
entweder ihr lasst die Leute, die die AP IS oder die
Schnittstellen entwickeln, die Dokumentation selber schreiben
oder ihr lasst euch helfen, entweder von solchen Menschen
die das professionell machen, die dann mit den Experten
zusammenarbeiten oder das ganze Halt in Kombination mit einer KI
Lösung machen. Hast du schon irgendwie so ein
bisschen eine Tendenz, in welche Richtung es für dich gehen
würde? Ja, wir werden uns dabei helfen.
Lassen von Technical Writern und auch tatsächlich dadurch, dass
wir einen Product Manager haben, werden wir jetzt auch zumindest
beim Aufbau dieser Dokumentation einen Projektmanager dabei
haben. Und wir haben es jetzt so ein
bisschen gesagt, so, ja so ein hybrides Modell, also die
Entwicklerinnen und Entwickler müssen das schon irgendwie
schreiben, aber halt so eine Rohversion, so einen Brain Dump
die. So für ihren Spezialteil der
Dokumentation Rotzen, die das dann da so hin.
Und dann haben wir halt Experten und Technical Writer, die das
dann ja die versuchen, daraus eine logische Geschichte
irgendwie zu schreiben. Am Ende liest du ja eine
Dokumentation, wie eine Geschichte, das muss ja alles
irgendwie in sich greifen und dann auch Sinn ergeben, und dazu
werden dann auch diese Technical Writer zum Beispiel Experten,
Interviewrunden führen. Teilweise mit den Leuten, die
diese Technologie geschrieben haben.
Und wenn ich jetzt, ich muss quasi mit jemandem, der sich
absolut gut mit unserem Identity Provider auskennt, der muss
eigentlich interviewt werden, zusammen mit der Person, die das
SDK geschrieben hat, damit ich dann die Dokumentation schreiben
kann, die mir sagt, wie ich, wenn ich eine App für unsere
Plattform baue, wie ich dafür sorgen kann, dass die Leute sich
über unseren. Ja, Plattform Account dann auch
in deine App einloggen können. Da müssen ja eigentlich 2 Dinge
zusammenlaufen und das muss ja sehr strukturiert beschrieben
werden, das ist ja auch nicht ganz einfach, das jemandem zu
beschreiben, dass sie vielleicht noch nie mit Identity Providern
auseinandergesetzt hat, auch hier wieder, was ist denn ein
Audience, ein Scope, ein Jwd, die all diese Tokens, die man da
irgendwie hat, und da wird dann schon ein Experte von uns, also
einer von unseren Developern, auch wahrscheinlich einen Tag
irgendwie pro Thema investieren müssen, das haben wir jetzt
zumindest mal so geplant, dass und am Ende wird das aber jetzt
zumindest beim Aufbau auch wirklich begleitet von Technical
writern. Das liegt auch ein bisschen
daran bei uns, dass wir eine relativ strikte Time man haben,
es gibt ein ganz festes Event, da muss diese Dokumentation
stehen, und da wird die dann auch auf Herz und Nieren auch
noch mal von ausgewählten Partnern und so was getestet.
Und deswegen haben wir auch einen gewissen Zeitdruck und
müssen jetzt relativ schnell auch relativ gute Qualität
abliefern. Und ich glaube, wenn man jetzt
so. Zuhört und vielleicht gerade
auch nicht. Das Budget hat aber einen
ähnlichen Qualitätsanspruch gibt es ja noch die Variante, dass
man KI einsetzt, ich denke mal ihr werdet KI kombinieren mit
quasi dem Premium, dass ihr einen Technical Writer heiern
könnt, der halt das ganze noch mal überarbeitet, noch mal
drüber schaut. Aber selbst wenn man das nicht
hat, kann man ja genau diesen Prozess auch ohne Durchlaufen.
Vielleicht nicht mit der gleichen Qualität am Ende, aber
ich kann natürlich auch die technischen Experten interviewen
und da irgendwie eine KI mitschreiben lassen und am Ende
wird da draußen passenden Text generieren lassen und dann
müssen halt die technischen Experten am Ende noch mal drüber
schauen und man es gibt vielleicht diesen Technical
Writer, ich glaube am Ende ist die Qualität nicht ganz so hoch,
weil ich glaube, wenn ein Mensch drüber ist.
Überschaut mit der Perspektive wie muss, muss etwas formuliert
sein, damit Menschen das verstehen, ist das immer noch
mal was anderes, aber ich glaube nicht, wir alle können uns das
Leisten für die Dokumentation, die wir schreiben, ja, das
stimmt schon, ich glaube, am Ende wird auch.
Diese Frage, wer schreibt die Docs wahrscheinlich auch durch
KI, irgendwie zunehmend irrelevant.
Viel relevanter ist eigentlich so ein bisschen, wer ist denn
der fachliche Eigentümer, also macht man, also ist das
eigentlich so eine Ownership oder?
Kulturfrage du musst ja schon fragen, wer ist denn dafür
zuständig, dass jetzt die Docs nicht verrotten und ist das
machst du Docs zum Beispiel als Teil von deiner Definition of
Done oder hast du ein eigenes gleich devrail Team?
Ich glaube Github und sowas, die können sich halt ein eigenes
Team an Developer Advocates und sowas leisten, die ja nichts
anderes tun als ihre. Produkte und ihre Plattformen
für Developer möglichst angenehm und cool zu machen oder bist du
hast du langfristig ein eigenes Redaktionsteam?
Aber ich glaube, diese Fragen musst du halt irgendwie klären.
Wer ist der fachliche Eigentümer von Dokumentationen, Wer stellt
sicher, dass Docs korrekt und auch aktuell bleiben?
Und ja, wir haben so ein bisschen eigentlich für uns
rausgearbeitet, dass es vielmehr eine Governance Frage ist als
eine, wer schreibt das jetzt Frage und das ist auch der
Grund, warum wir jetzt bei Jtl zumindest für das Thema
Developer Dokumentation. Zumindest mal einen eigenen PM,
einen eigenen Produktmanager haben.
Das heißt, Ihr habt jetzt schon so ein bisschen.
Die Reise begonnen ihr habt einiges gelernt.
Angenommen, du würdest jetzt noch mal ganz von Anfang
anfangen, was würdest du anderen mitgeben, die jetzt diese Reise
gerade erst beginnen und sagen, wir bauen gerade ein neues
Produkt mit einer entsprechenden für eine entsprechende Developer
audience mit irgendwelchen. Programmierschnittstellen und
müssen dafür eine Doku bauen. Wie sollte man deiner Meinung
nach anfangen? Ja, ich würde mich erstmal für
irgendeinen Anbieter. Entscheiden für mich war
absolute Vorgabe, dass die Markdown oder zumindest
irgendein markdown ähnliches Format, zum Beispiel Mdx oder
sowas unterstützen, sodass ich halt auch relativ flexibel bin
und dass vielleicht auch irgendwie das Teil davon auch
einfach für github benutzen kann.
Für die Read me Page und also, dass zumindest markdown
irgendwie als fertiges Format ist.
Und dann war der erste Gedanke, über den wir uns auch erstmal
klar machen mussten, nehmen wir einen Anbieter, der das für uns
hostet. Wir haben uns jetzt bei Jtl für
Mintlify entschieden, aber ich kann ja auch so was nehmen wie
Re dogly, die können auch vieles, sind deutlich günstiger,
es gibt so was wie Dukosaurus, das ist auch so eine Open Source
Alternative auch extrem gut. Ich habe auch schon mal eine
damals für Space Blogs, das ist diese Permission Engine die wir
mal gebaut haben gibt es auch eine Podcast Folge zu?
Haben wir Docusaurus genommen, damit auch extrem gute
Erfahrungen gemacht hat und eine riesen Community muss ich aber
selber betreiben und erstmal würde ich sagen okay wo baue ich
denn meine developer Dokumentation, weil das schränkt
ja auch manchmal so ein bisschen ein.
Welche Features kann ich denn nachher nutzen und die Auswahl
die ich da treffe, die muss natürlich auf dieses Set passen,
was ich mir da überlegt habe, also wenn ich mir Stripe oder
auch Zero als Vorlage nehme und auch so Fancy sein will wie die.
Dann fallen natürlich auch Anbieter raus, die solche Dinge
gar nicht können und daher muss ich jetzt eigentlich erst mal
die Auswahl treffen. Mit wem mache ich es denn
eigentlich und was ist denn so dieses von diesen coolen
Features? Das Feature Set was ich
überhaupt haben will und eine Frage, die ich jetzt an der
Stelle. Noch stellen muss so Reality
Check, weil ja im Moment immer über die große Gefahr für saas
Unternehmen gesprochen wird, weil alle mit KI sich ihre
Lösungen selber bauen. Würdest du dringend davon
abraten, so eine Dokumentationslösung selber zu
vipe coden? Och weiß ich gar nicht.
Nee, ich würde sagen. Nicht unbedingt.
Ich halte das durchaus für möglich.
Ich glaube, dass das in manchen Stellen kein Hexenwerk ist.
Zumindest wenn ich sage, ich brauche diese ultra Fancy fancy
Features nicht, wenn ich mich da jetzt einloggen kann und das
irgendwo in meinen API Key noch irgendwo rauszieht, dann würde
ich da zumindest beim Vipe Coden sehr genau drauf gucken, weil
das ja eine sehr sicherheitsrelevante Sache ist.
Aber sonst? Jetzt ganz, ganz blöd und
plakativ gesagt, so ein bisschen markdown zu rendern, da wird es
auch coole KI Lösungen für geben, wenn für alles, was dann
irgendwie so ein bisschen fanciger wird, kann man sich das
bestimmt auch Vibe Coden, von daher würde ich das als
Plattform gar nicht ausschließen, dann würde ich
aber gucken, dass ich da halt auf jeden Fall mitgebe, dass
auch das Produkt was nachher entsteht AI first gedacht ist.
Also so eine LMS txt zu schreiben, das kostet
wahrscheinlich. Wenn man sagt, wenn man der KI
sagt, Ey, Mach alle Sachen, die da drin stehen, bereite die auch
in so einer Lems. Txt auf, kostet mich das keine
30 Minuten sowas zu bauen. Gibt aber allen anderen Usern,
die KI benutzen sofort einen Mehrwert, die irgendwie auf
meine auf meine Docs sind. Und zwar würde ich der KI die
das Vibe Codet oder auch meinem Anbieter den ich am Ende
verwende auf jeden Fall auch sagen von Anfang an da
irgendeine Form von Analytics einzubauen.
Was nutzen die Leute, welche Seiten verlassen sie schnell,
wie das, welche Seite scrollen Sie gar nicht bis zum Ende?
Und das wird dann natürlich irgendwie auch mein Backlog, ja
werden von Dingen, die ich baue. Und dann würde ich sagen, kann
man natürlich auch selber Dokumentationen gewipe, coden,
zumindest die Plattform da drumherum.
Den Content würde ich glaube ich ein bisschen, ja, ich glaube,
keiner will irgendwie so eine komplett ki geschriebene
Dokumentation lesen, ich habe glaube ich auch mal bei der Open
Cloud Folge gesagt, dass man der Open Cloud Dokumentation sehr
anmerkt, dass sie gewipecoded ist, zumindest inhaltlich.
Und das auch teilweise wirklich sehr frustrierend, weil war,
weil da stand ganz viel, aber oft nichts, also oft nicht das,
was man dann wirklich gesucht hat, sondern es hat sich dann so
durch KI mäßig, so ein bisschen aufgebläht gefühlt, hat sich oft
wiederholt, so ein bisschen wie wir hier in dem Podcast, nur
dass wir gar keine KI verwenden für unsere Sprache, aber die
Plattform, ja den Content, nein und ich dann frage.
Kurz beantworten super und wir haben jetzt ja ganz lange
darüber. Gesprochen, was für uns eine
gute Dokumentation ausmacht, aber uns würde natürlich auch
interessieren, was für euch die zuhört, eine gute Doku ausmacht.
Gebt uns gerne ein paar Beispiele und Feedback per e
Mail per Spotify Kommentare oder auf youtube könnt uns auch
direkt ein paar Beispiele geben und sagt Hey den Service habe
ich letztens genutzt und den habt ihr gar nicht erwähnt, die
haben eine großartige Doku, lasst uns das gerne wissen,
können wir natürlich dann auch entsprechend.
In den eigenen Projekten von lernen gerne.
Wir sammeln coole Dokumentationsbeispiele.
Also ich kann auch auf Post Talk noch mal verreisen, die haben
auch eine wahnsinnig coole Webseite, einfach, die ist so
ein bisschen wieso ein altes Computerbetriebssystem
aufgebaut, da finde ich ist ganz cool, gibt so ein so ein
Mülleimer Icon und da sind dann die ganzen Konkurrenten, sind
dann in diesem Mülleimer drin und so das ist wirklich, also
das macht einfach auch Spaß sich irgendwie damit zu beschäftigen.
Und ich muss sagen, wir hatten jetzt auch viel Spaß, uns mit
dem Thema zu beschäftigen, weil es wirklich nah unter unserem
Job dran ist. Und wenn man so wirklich von
Developern für Developer irgendwas schreibt, das ist
immer cool. Und wenn ihr jetzt auch
irgendwie gemerkt habt, ey, das macht ja, das hat sich nach Spaß
angehört, dann nicht vergessen. Wir heiern also wenn ihr noch
einen coolen Job bei Jtl sucht, irgendwo in der Software oder in
der Cloud oder in der KI Branche, schaut da auf jeden
Fall noch mal in die Links rein, die wir in den Show Notes haben
und wenn da nichts dabei ist, schickt mir auch sehr sehr gerne
eine Initiativbewerbung. Auch sonst gerne an die E Mail
Adresse hier von dem Podcast. Dann leite ich das weiter, weil
nur das natürlich. Also ich finde es wahnsinnig
coole Themen und ich hoffe euch hat es auch Spaß gemacht hier so
ein bisschen dieses Kick ass Developer dokumentations Ding
mir gemeinsam zu erforschen und selbst wenn ihr.
Gerade keinen neuen Job sucht, könnt ihr uns trotzdem einen
Gefallen tun und uns gerne eine positive Bewertung für diese
Podcast Folge oder den Podcast allgemein da lassen.
Das könnt ihr auf den. Bekannten Plattformen wie
Spotify oder Apple Podcast. Und wir freuen uns natürlich
auch immer sehr, wenn ihr uns über bei mir Coffee einen Kaffee
ausgebt oder wenn ihr zu eurem eigenen.
Kaffee die passende to do Cast Gebrandete Nerd Tasse haben
wollt, dann schaut auch gerne in unserem kleinen Shop vorbei.
Links zu all dem findet ihr in der Beschreibung von der Podcast
Folge zusammen mit allem, was wir hier besprochen haben und.
Und natürlich freuen wir uns auch, wenn ihr.
Nächsten Montag wieder mit dabei seid.
Wir machen immer abwechselnd eine Themenfolge wie diese und
eine News Folge, das heißt nächste Woche gibt es dann
wieder die aktuellen Tech und Developer News, bis dahin habt
eine gute Zeit. Schreibt oder dokumentiert ganz
viel Code bis dahin.