Sonntag , Oktober 11 2020

So erstellen Sie ein flexibles Entwicklerdokumentationsportal

Blog

Die Entwicklung von Analyse-Apps ist eine neue Richtung für Produktteams. In der Toolbox sprechen wir über Best Practices, Tipps, Tricks und Erfolgsgeschichten für die Entwicklung, um Ihnen dabei zu helfen, die Zukunft der Analyse zu gestalten und Ihren Benutzern die erforderlichen Erkenntnisse und Aktionen zu liefern.

Beim Erstellen einer Ressource Um Entwicklern dabei zu helfen, das Beste aus Ihrem Produkt herauszuholen, ist es wichtig, dass sie einen Beitrag zur Entwicklerdokumentation leisten können und nicht nur alle Inhalte von Produkt- oder Technikern stammen.

Wenn Sie nicht gelesen haben, wie wir unser Entwicklerportal kürzlich überarbeitet haben, lesen Sie unser vorheriges Gespräch mit Moti Granovsky, Sisense's Head of Developer Relations. In diesem zweiten Teil werden wir uns eingehender mit der Frage befassen, wie wir ein neues System von Grund auf aufgebaut haben, um sowohl großartige Informationen zu liefern als auch flexibel genug zu sein, um eine kontinuierliche Entwicklung und Wachstum zu ermöglichen.

Beginnen wir unsere Reise in die Wiederherstellen, indem wir verstehen, was unsere Anforderungen waren und wie wir sie erfüllt haben.

Bauen statt kaufen

Shruthi Panicker: Warum haben wir uns entschieden, das Portal von Grund auf selbst zu erstellen und nicht nur eines von ihnen zu verwenden die vielen großartigen Produkte da draußen?

Moti Granovsky: Es gibt großartige Produkte, die sich auf Entwicklerdokumentation konzentrieren und von vielen Unternehmen erfolgreich eingesetzt werden. Als wir mit dem Wiederaufbau des Portals begannen, wussten wir, dass Ingenieure einen Beitrag zu unserer Entwicklerdokumentation leisten sollten. Wir wollten auch einige Inhalte automatisch generieren, insbesondere API-Referenzen (die sehr trocken sind; es ist kein "Schreiben" erforderlich). Unser Produkt verfügt über so viele APIs (umfangreich und umfangreich), dass das Schreiben und Verwalten dieser APIs sehr zeitaufwändig ist. Wir wollten nicht, dass Tech-Autoren Zeit damit verschwenden, Tabellen und Parametertabellen wiederholt zu aktualisieren.

Wir wollten unsere Zeit in die Erstellung ansprechenderer und wertvollerer Inhalte wie Tutorials, Open-Source-Demos, coole Funktionen usw. investieren.

Machen Sie Ihre Anforderungen spezifisch

SP: Was Wurden Sie dazu aufgefordert?

MG: Unsere Anforderungen lauteten im Wesentlichen:

  1. Die Plattform sollte es uns ermöglichen, das Styling vom Inhalt zu trennen. Wir wollten sicherstellen, dass sie im Gegensatz zur alten Website gut aussieht, zur Marke Sisense passt und auch dann noch gut aussieht, wenn mehr Inhalte hinzugefügt werden. Dies bedeutet, dass wir nicht nur den Inhalt mit einem White-Label versehen und gestalten wollten, sondern auch das Layout und das Design vom Inhalt trennen wollten. (Denken Sie daran, dass die Leute, die Dokumentation schreiben, nicht unbedingt Experten für visuelles Design sind.)
  2. Das Format sollte Entwicklern zugänglich sein (auch bekannt als Markdown-basiert). Neben einem UI-basierten Editor verfügen einige Content-Management-Systeme über eine eigene Sprache zum programmgesteuerten Formatieren von Inhalten. Oft weiß jedoch niemand genug über diese Sprachen und sie sind auch nicht sehr intuitiv. Stattdessen haben wir uns die gängigste Methode für Entwickler angesehen, Inhalte zu schreiben – Markdown. Es wird von Git selbst und allen Git-Anbietern verwendet. Sogar Readme-Dateien für Projekte werden in Markdown geschrieben. Jeder Entwickler kennt diese Syntax und hat den Vorteil, dass Design von Inhalt getrennt wird. Markdown-Inhalte ermöglichen es uns auch, Inhalte automatisch zu generieren. Wenn Sie sich umschauen, können die meisten API-Tools wie Swagger beispielsweise Markdown-Inhalte generieren.
  3. Unsere Kunden sollten (eventuell) einen Beitrag zu Dokumenten leisten können. Wenn ein Kunde einen Tippfehler oder einen Fehler findet oder Details hinzufügen möchte, möchten wir dies ermöglichen. Dafür sollten wir in der Lage sein, den Inhalt an einem öffentlichen Ort zu speichern, beispielsweise in einem GitHub-Repository. Markdown macht dies möglich, da es sich um ein Textformat handelt, das problemlos in GitHub geteilt werden kann. Wir müssen jedoch den Inhalt von der Website selbst trennen (etwas, das öffentlich verfügbar ist). Wenn wir HTML-Seiten schreiben und auf einen Server stellen, kann ein Kunde nicht dazu beitragen. Wenn diese Seiten jedoch aus etwas generiert werden, das öffentlich zugänglich ist, wie z. B. einem GitHub-Repository, können wir diese Herausforderung lösen.
  4. Wir sollten über die reine Dokumentation hinausgehen. Wir wollten, dass die neue Website ein echtes Entwicklerportal ist – ein Wissens- und Informationszentrum für Entwickler, mit dem sie alle benötigten Ressourcen finden können. Wir möchten sicherstellen, dass es in Zukunft einen Blog, einen Spielplatz, Links zur Community usw. enthält, die nicht unbedingt dokumentiert sind. Wir möchten ein Zuhause für Entwickler schaffen, in dem sie alles finden können, was sie für ihre Arbeit benötigen.

Wir haben uns Produkte auf dem Markt angesehen, und keines von ihnen hat alle diese Anforderungen zusammen erfüllt. Darüber hinaus waren sie relativ kostspielig, da sie Hosting beinhalten. Die Dokumentation besteht jedoch im Allgemeinen aus statischen Inhalten, sodass sie billig und einfach zu hosten ist. Es gab keinen Grund, warum wir es nicht selbst erstellen konnten, da wir über das technische Know-how verfügen, um es intern zu erstellen.

 sisense-blog-Embedded-Trends-20191218-bl-blog-banner "class =" wp- image-85013 "srcset =" https://cdn.sisense.com/wp-content/uploads/sisense-blog-Embedded-Trends-20191218-bl-blog-banner.jpg 770w, https: //cdn.sisense. com / wp-content / uploads / sisense-blog-Embedded-Trends-20191218-bl-blog-banner-370x120.jpg 370w, https://cdn.sisense.com/wp-content/uploads/sisense-blog-Embedded -Trends-20191218-bl-blog-banner-768x249.jpg 768w, https://cdn.sisense.com/wp-content/uploads/sisense-blog-Embedded-Trends-20191218-bl-blog-banner-178x58. jpg 178w, https://cdn.sisense.com/wp-content/uploads/sisense-blog-Embedded-Trends-20191218-bl-blog-banner-616x200.jpg 616w, https://cdn.sisense.com/ wp-content / uploads / sisense-blog-Embedded-Trends-20191218-bl-blog-banner-356x116.jpg 356w "Größen =" (maximale Breite: 770px) 100vw, 770px "/> </figure>
<h2> Wählen Sie das richtige Framework </h2>
<p><strong> SP: </strong> Also, welche Werkzeuge haben Sie d ecide für den Bau des neuen Portals? </p>
<p><strong> MG: </strong>Wir haben herausgefunden, dass einige Unternehmen (und ein großes Dankeschön an das Developer Relations-Team von Okta, dessen Herangehensweise an Entwicklerdokumente uns inspiriert hat) diesen anderen Ansatz gewählt haben und bauten ihre eigenen Websites mit verschiedenen Tools. Es gibt Frameworks, die Websites aus Markdown generieren können. Wir haben uns verschiedene angesehen und eine ausgewählt, die zum Sisense-Technologie-Stack passt (in Bezug auf Sprachen, mit denen Entwickler vertraut sind. Da die meisten unserer Entwickler JavaScript-Entwickler sind, wollten wir eine, die diese verwendet und nicht beispielsweise Python). [19659006]  Wir haben eine namens VuePress gefunden, die genau das tat, was wir brauchten. Es hat die ganze Flexibilität der Welt. Es ist ein Open-Source-Framework, das vom Vue.js-Projekt erstellt und verwendet wird. Auf diese Weise konnten wir genau die Art von Website erstellen, die wir in Bezug auf das Erscheinungsbild im Sinn hatten, und gleichzeitig viel Aufwand vermeiden, anstatt von vorne zu beginnen.</p>
<p> Wir haben Anstrengungen unternommen, um ein großartiges Design zu erstellen und viele zu überarbeiten den vorhandenen Inhalt hatten wir in Markdown aus dem alten Format. Mit diesem Prozess können wir das neue Portal jedoch von Grund auf genau so erstellen, wie wir es möchten, ohne Kompromisse eingehen zu müssen. </p>
<p> Während es anfangs viel Mühe gekostet hat, wird sich auf lange Sicht alles auszahlen. Erstens ist das Hosting sehr billig. Zweitens müssen wir nichts entwerfen, wenn wir neue Inhalte hinzufügen müssen. Es wird nur so teuer sein wie das Schreiben dieses Textes. Jeder kann einfach Text in einen Notizblock schreiben und schöne Inhalte auf der Website haben. </p>
<h2> Neues Portal, neue Optionen </h2>
<p><strong> SP: </strong> Was können Benutzer von dem neuen Portal erwarten, das sie im Internet nicht finden konnten? alte? </p>
<p><strong> MG: </strong> Aufgrund des neuen Designs gibt es einige große Änderungen im neuen Sisense-Entwicklerportal: </p>
<ul>
<li><em> Trennung von API-Referenz und Dokumentation: </em> Entwickler können eine dedizierte finden API-Referenzabschnitt, der gut organisiert und strukturiert ist. Sie können schnell auf die genauen Informationen zugreifen, die sie benötigen. Es ist viel detaillierter und viel standardisierter als das, was wir zuvor hatten, und sie müssen nicht durch eine Reihe von Texten scrollen, um auf das zuzugreifen, was sie benötigen. </li>
<li><em> Weitere Codebeispiele direkt in der Dokumentation: </em> Code kann einfach mit einer Kopiercode-Schaltfläche kopiert werden. Es ist schön formatiert und die Syntax wird entsprechend der Sprache hervorgehoben, was das Lesen erheblich erleichtert. </li>
</ul>
<figure class= Portal
  • Viel mehr Querverweise und Links als früher: Wenn etwas erwähnt wird , es ist immer genau dort verlinkt, oder Sie finden den entsprechenden Link am Ende Ihrer Seite. Sie können navigieren und das gesamte Wissen erwerben, um eine Aufgabe zu erledigen, ohne den Denkprozess zu unterbrechen.
  • Verbesserte Suche: Sie können Suchseiten und Überschriften innerhalb von Seiten schnell anzeigen. Sie können schnell in bestimmte Bereiche innerhalb einer Seite springen.
 Suche innerhalb eines Seiten-Screenshots
  • Responsive Mobile Experience: Wir haben auch alle Seiten für den mobilen Verbrauch optimiert.
  • Neue und überarbeitete Inhalte: Vieles, was dem Portal hinzugefügt wurde, ist völlig neu Wir haben viele vorhandene Inhalte überarbeitet, neu validiert und aktualisiert.
  • Breites Spektrum an Inhaltstypen: Wir haben unserem GitHub-Konto viele externe Verweise, auf Vimeo gehostete Webinare und einen in Verbindung mit dem Entwicklerportal.

Insgesamt ist der Inhalt jetzt nicht nur ein Textblock, sondern Teil eines Wissensökosystems, das Entwickler nutzen können. Jeder hat einen anderen Lernprozess. Einige lesen lieber, andere sehen lieber eine Demo, andere sehen sich gerne ein Video an, während andere lieber direkt eintauchen und durch Experimente lernen. Wir versuchen, verschiedene Möglichkeiten bereitzustellen, um zu helfen, unabhängig davon, wie eine Person lernt.

Darüber hinaus bieten wir folgende Funktionen:

  • Versionshinweise für Entwickler und Versionshinweise für die Website selbst, damit Sie nachverfolgen können, was sich geändert hat.
  • Weitere Informationen zum DevX-Team, warum wir existieren und und wie man mit uns in Kontakt tritt
  • Möglichkeit, den Spielplatz, das Blog und die Foren direkt über das Portal zu erreichen

In Zukunft möchten wir ein entwicklerorientiertes Blog innerhalb des Portals hinzufügen Portal direkt. Wir arbeiten auch kontinuierlich an mehr Videoinhalten und Dokumentationen für einige der APIs, die noch nicht behandelt wurden.

Wie Sie Ihre eigene Dokumentation verbessern können

SP: Schließlich, wie kann eine Organisation entscheiden, ob sie erstellt Eine eigene Entwicklerdokumentationsseite ist der richtige Ansatz für sie?

MG: Berücksichtigen Sie diese Punkte, um zu entscheiden, ob dieser Ansatz für Sie gut ist:

  • Sie benötigen technische Fähigkeiten, um die zu erstellen Webseite.
  • Sie müssen sicherstellen, dass die Personen, die Dokumentationen schreiben, mit dem Format vertraut sind. Wenn es sich bei den Personen, die in Ihrer Organisation Dokumentationen schreiben, um technische Redakteure handelt, die mit Markdown vertraut sind, sollten Sie diesen Ansatz verwenden. Oder vielleicht wollen sie lernen, dann ist das auch toll. Wenn sie nicht lernen möchten, benötigen sie möglicherweise eine andere Plattform, die genau das ist, was Sie sehen und was Sie erhalten.
  • Stellen Sie sicher, dass Sie über die IT-Fähigkeit verfügen, die Site zu hosten und zu warten. Wenn Sie nicht sicherstellen können, dass es weltweit verfügbar und rund um die Uhr verfügbar ist, treten Probleme auf. Da dies die größte Schnittstelle mit der größten Oberfläche ist, haben Fehler oder Ausfallzeiten enorme negative Auswirkungen.

Alles läuft auf Kapazität und Bedarf hinaus. Wenn Ihre aktuelle Dokumentationswebsite funktioniert und die Kunden damit zufrieden sind und Sie lediglich den Inhalt verbessern und aktualisieren müssen, tun Sie dies. Verschwenden Sie Ihre Zeit und Ihr Geld nicht damit, etwas Neues zu bauen. Wenn Sie jedoch wie wir viel Raum für Verbesserungen haben und die Gelegenheit nutzen möchten, die Benutzererfahrung zu aktualisieren und zu überarbeiten, ist dies eine praktikable Lösung, die in Betracht gezogen werden sollte.

 Erstellen eines besseren Entwicklerdokumentationsportals [19659054] Shruthi Panicker </strong> ist Senior Technical Product Marketing Manager bei Sisense. Sie konzentriert sich darauf, wie Sisense genutzt werden kann, um erfolgreiche Embedded Analytics-Lösungen zu entwickeln, die die Einbettungs- und Anpassungsfunktionen von Sisense, die Initiative zur Entwicklererfahrung und die Cloud-native Architektur abdecken. Sie hat einen BS in Informatik sowie einen MBA und verfügt über mehr als ein Jahrzehnt Erfahrung in der Technologiewelt. </em></p>
</div>
</pre>
<div class=

About BusinessIntelligence

Check Also

Was ist Geofencing und wie kann es Ihnen helfen, Ihr Geschäft auszubauen?

Das moderne Geschäft befindet sich jetzt in einem hart umkämpften Umfeld, in dem es bereits …

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.