Auf der bevorstehenden APIStrat-Konferenz in Portland wird Taylor Barnett verschiedene Prinzipien des Dokumentationsdesigns untersuchen und Best Practices diskutieren.
Taylor Barnett, Community Engineer bei Keen IO, sagt, dass Übung und ständige Iteration der Schlüssel zum Schreiben einer guten Dokumentation sind. Auf der bevorstehenden API Strategy & Practice Conference 2017, die vom 31. Oktober bis 2. November in Portland stattfindet, wird Barnett die verschiedenen Arten der Dokumentation erläutern und einige der Best Practices skizzieren.
In seinem Vortrag – „Dinge, von denen ich möchte, dass die Leute mir beim Schreiben von Dokumentationen erzählen“ – wird Barnett untersuchen, wie Menschen Dokumentation verwenden, und Tools und Taktiken diskutieren, um andere Teammitglieder in das Schreiben von Dokumentationen einzubeziehen. Barnett erklärt in diesem bearbeiteten Interview ausführlicher.
Linux Foundation: Was hat Sie zu diesem Gespräch geführt? Haben Sie Projekte mit schlechter Dokumentation gesehen?
Taylor Barnett: Letztes Jahr leiteten meine Teamkollegin Maggie Yang und ich die Bemühungen zur Verbesserung der Inhalte und der Entwicklerdokumentation bei Keen IO. Es ist kein Geheimnis, dass Entwickler großartige Dokumentation lieben, aber viele API-Unternehmen sind nicht immer mit den Ressourcen ausgestattet, um eine zu haben. Infolgedessen stoßen wir alle auf eine Menge schlechter Dokumentation, wenn wir versuchen, Entwicklertools und APIs zu verwenden.
Linux Foundation: Oft gibt es ein Dokumentationsteam und Entwickler, die eine Software geschrieben haben; beide sind Experten auf ihrem Gebiet, aber sie müssen gut zusammenarbeiten können, um eine brauchbare Dokumentation zu erstellen. Wie kann dieses Niveau der Zusammenarbeit erreicht werden?
Barnett: In großen Unternehmen kann das durchaus stimmen, obwohl in vielen Unternehmen die Dokumentation immer noch verschiedenen Teams gehört. Allerdings muss das Zusammenspiel noch verbessert werden. Eine Möglichkeit, die Zusammenarbeit zu verbessern, besteht darin, frühzeitig im Produktentwicklungsprozess Dokumentation zu schreiben. Wenn Sie warten, bis alles fertig ist und das Produkt zur Veröffentlichung bereit ist, fühlen sich die Personen, die die Dokumentation schreiben, vom Prozess abgekoppelt und sehen sich selbst als zweitrangig an. Wenn Mitarbeiter der Produktentwicklung frühzeitig zusammenarbeiten, verbessert sich nicht nur das Produkt, sondern auch die Dokumentation. Personen, die Dokumentation schreiben, verbringen normalerweise einige Zeit damit, die API oder das Tool zu verstehen, über das sie schreiben, sodass sie nur besser werden, wenn sie mit den Personen zusammenarbeiten können, die das Produkt entwickeln. Außerdem können sie viel früher mehr Feedback aus Benutzersicht geben.
Eine weitere Möglichkeit zur Verbesserung der Zusammenarbeit besteht darin, mehr Personen in den Überprüfungsprozess der Dokumentation einzubeziehen. Wir führen die meisten unserer Dokumentationsüberprüfungen auf GitHub durch. Es ist großartig, dass der Code nicht nur von jemandem in der Rolle eines Redakteurs überprüft wird, sondern auch von Leuten aus dem Engineering-Team und dem Produktionsteam. Dies erhöht die Anzahl der abwechslungsreichen Ansichten der Dokumentation und hilft, sie zu verbessern.
Linux Foundation: Wie sollten Entwickler an die Dokumentation herangehen?
Barnett: Die meisten Entwickler sind mit der Idee von Test Driven Development (TDD) sehr vertraut, aber wie vertraut sind sie mit Documentation Driven Development (DDD)? DDD-Schritte:
- Dokumentation schreiben oder aktualisieren,
- Feedback zu dieser Dokumentation einholen,
- Schreiben Sie einen Fehlertest gemäß dieser Dokumentation (TDD),
- Schreiben Sie den Code, um den Fehlertest zu bestehen,
- Wiederholen.
Dies kann eine großartige Möglichkeit für Entwickler sein, viel Zeit zu sparen und nicht zu viel Zeit mit schlecht gestalteten Funktionen zu verbringen. Wie Isaac Schlüter, Mitbegründer von npm, über die Dokumentationsentwicklung sagt: „Es ist ein effektiver Weg, die Produktivität zu steigern, indem sowohl die Fehlerquote als auch die Kosten gesenkt werden.“ Unser Gehirn kann nur eine begrenzte Menge an Informationen auf einmal speichern. Aus Computersicht ist unser Arbeitsgedächtnis ziemlich klein. Aufzuschreiben, worüber wir nachdenken, ist eine Möglichkeit, „einen großen Teil der Gedanken ohne Datenverlust abzuladen“, wodurch wir langsamer und sorgfältiger denken können.
Zum Beispiel: Bei Keen IO haben wir kürzlich unsere JavaScript-Bibliothek in drei verschiedene Module aufgeteilt. Diese Entscheidung wurde durch die von uns gepflegte Dokumentation inspiriert. Wir haben versucht, die Dokumentation zu rationalisieren, aber es war zu viel, um alles mit begrenzter Aufmerksamkeit abzudecken. Viele wichtige Details und Funktionen wurden im Rauschen verborgen. Wenn beispielsweise die gesamte Dokumentation früher geschrieben worden wäre, hätten wir diese Entscheidung möglicherweise früher getroffen.
Außerdem sind für einen Entwickler, der selbst Dokumentationen schreibt, ständige Wiederholungen und Übungen wichtig. Ihre erste Version der Dokumentation wird nicht großartig sein, aber indem Sie sich darauf konzentrieren, verständlichen Text zu schreiben, wird sie mit der Zeit besser. Es ist auch wichtig, dass eine andere Person, die mit dem Produkt nicht vertraut ist, Ihre Dokumentation überprüfen kann.
Linux Foundation: Wenn Entwickler Dokumentationen für andere Entwickler schreiben, wie können sie dann wie Benutzer denken?
Barnett:
Früher dachte ich, dass Entwickler die besten Leute sind, um Dokumentationen für andere Entwickler zu schreiben, weil sie einer sind. Ich denke immer noch, dass dies teilweise wahr ist, weil Einige Entwickler haben viel Wissen. Wenn einige Zeit vergangen ist, seit der Entwickler etwas gelernt hat, kann es zu einem sogenannten „Fluch des Wissens“ kommen. Je mehr man weiß, desto mehr vergisst man, wie es vorher war. Deshalb spreche ich gerne von empathischer Dokumentation.
Sie müssen sich in den Benutzer am anderen Ende einfühlen. Gehen Sie nicht davon aus, dass er weiß, wie man etwas macht, geben Sie dem Benutzer die Ressourcen, um Schritte auszuführen, die Sie möglicherweise als „einfach“ empfinden. Auch die Vorstellung, dass etwas „einfach“ oder „einfach“ ist, wenn es für den Benutzer nicht funktioniert, ist das beängstigendste Gefühl für den Benutzer. Es lässt Ihre Benutzer an sich selbst zweifeln, sich frustriert fühlen und eine Reihe anderer negativer Emotionen hervorrufen. Versuchen Sie immer daran zu denken, dass Sie einfühlsam sein müssen!
Linux Foundation : Wie wichtig sind Dokumentationstools?
Barnett: Sehr wichtig! Zuvor habe ich die Verwendung von GitHub für Reviews erwähnt. Ich würde auch empfehlen, fortlaufende Integrationstests auf Ihrer Dokumentationsseite durchzuführen, wenn Sie keinen Dienst wie ReadMe oder Apiary verwenden, um sicherzustellen, dass Sie ihn nicht beschädigen. Verwandtes Thema: Entwickeln Sie Ihr eigenes Produkt oder nutzen Sie einen Dienst? Tools können hilfreich sein, sind aber nicht immer optimal. Sie müssen ein Gleichgewicht finden, das auf Ihren aktuellen Ressourcen basiert. Abschließend würde ich empfehlen, das Buch von Ann Gentle, Docs Like Code, auszuprobieren. Sie spricht das Thema Werkzeuge viele Male in dem Buch an.
Linux Foundation: Wer sollte an Ihrer Sitzung teilnehmen?
Barnett: Alle! Ich mache nur Spaß. Wenn Sie jemand in einer Entwicklerrolle sind, wie z. B. Beziehungsentwickler, Evangelisten, Fürsprecher, Vermarkter usw., wenn Sie als Produkt- oder Plattformentwickler in einem Produktionsteam sind, oder wenn Sie ein Entwickler oder Ingenieur sind, der großartige Dokumentationen schreiben möchte .
Linux Foundation: Was ist die Hauptbotschaft Ihres Gesprächs?
Barnett: Jeder kann Dokumentationen schreiben, aber mit etwas Übung, Iteration und der Arbeit an verschiedenen Schreibfähigkeiten kann jeder großartige Dokumentationen schreiben.
Erfahren Sie mehr in Taylor Barnetts Vortrag auf der APIStrat vom 31. Oktober bis 2. November in Portland, Oregon.
