Möchten Sie Ihren Prozess zur Produktdokumentation optimieren, ohne technisches Fachwissen zu benötigen? Apidog bietet eine umfassende Lösung, die Produktmanagern und Operationsteams ermöglicht, nahtlos bei der Erstellung, Verwaltung und Veröffentlichung professioneller Dokumentationen zusammenzuarbeiten. Mit seiner intuitiven Benutzeroberfläche, Echtzeit-Kollaborationsfunktionen und wartungsfreier Veröffentlichung verändert Apidog die Art und Weise, wie Teams Dokumentations-Workflows angehen.
Jedes Produkt benötigt eine eigene Dokumentation. Selbst wenn Ihr Produkt eine kundenorientierte Anwendung mit sehr intuitivem und einfachem Interaktionsdesign ist, wird es immer noch Bereiche geben, die mehr Erklärung benötigen, aber die Komplexität erhöhen würden, wenn sie direkt in der Produktoberfläche präsentiert würden. Daher sind Dokumentenmanagement, -wartung und -veröffentlichung entscheidende Anliegen für jedes Produkt.
Beim Erstellen von Produktdokumentationen verwenden Teams typischerweise fertige Dokumentationstools wie Notion, oder Content-Management-Tools wie Confluence und CMS, oder Dokumentationsgeneratoren wie Docusaurus und Gitbook. Diese Lösungen stoßen jedoch oft auf die folgenden Probleme:
- Die Dokumentation erfordert Codierung zum Schreiben, mit hohen Kosten. Selbst nachdem die Dokumentation geschrieben wurde, bleibt das tatsächliche Leseerlebnis oft hinter den Erwartungen zurück;
- Die Dokumentation erfordert die Zusammenarbeit mehrerer Rollen, was die Versionsverwaltung erschwert und es schwierig macht, Optimierungsvorschläge an andere zu kommunizieren;
- Die Veröffentlichung fertiger Dokumentationen in der Produktionsumgebung ist entweder zu einfach oder zu komplex, was potenziell technische Prozesse beinhaltet, die für nicht-technische Kollegen schwer zu handhaben sind und zu Fehlern führen können.
Das Apidog-Team verwendete zuvor Docusaurus, um unsere Dokumentation zu erstellen. Da unsere Dokumentation kontinuierlich iteriert wurde, stießen wir auch auf einige der oben genannten Probleme. Nachdem wir unsere Erfahrungen und gelernten Lektionen zusammengefasst hatten, entwickelten wir Lösungen und integrierten sie in Apidog. Nun wurde die Produktdokumentation des Apidog-Teams vollständig zu Apidog migriert, wobei die gesamte Erstellung und Präsentation von Apidog übernommen wird.
Ich werde unsere Praxis teilen, wie man Produktdokumentation mit Apidog erstellt. Zuvor, wenn Sie die spezifischen Effekte der Apidog-Produktdokumentation genauer betrachten möchten, können Sie die Apidog-Hilfedokumentation überprüfen – Feedback ist willkommen.
Hintergrund
Bevor wir unsere Praxis vorstellen, gibt es einige Kontexte, die zuerst erklärt werden müssen, damit jeder besser verstehen kann, warum wir die Dinge auf diese Weise tun. Die Produktdokumentation unseres Unternehmens wird in der Regel gemeinsam von Kollegen aus den Produkt- und Operationsabteilungen erstellt. Der Hauptprozess ist wie folgt:
Der obige Prozess erfordert keine Beteiligung von technischem Personal – alle produkt-dokumentationsbezogenen Vorgänge werden von Kollegen aus diesen beiden Abteilungen abgeschlossen. Als Nächstes werde ich erklären, wie die Aufgabe der Erstellung von Produktdokumentation mit Apidog gemäß diesem Prozess abgeschlossen wird.
Kernprozess
1. Einen Sprint-Branch für Content-Management und Zusammenarbeit erstellen
Nachdem eine Entwicklungsiteration beginnt, erstellen Operations-Kollegen einen Iterations-Branch in Apidog, um alle Dokumente, die Änderungen in der aktuellen Iteration betreffen, in diesem Branch zur Zusammenarbeit zu platzieren und so direkte Auswirkungen auf den Haupt-Branch zu vermeiden.
Nach der Erstellung importieren Produktmanager bestehende Dokumente, die geändert werden müssen, basierend auf den tatsächlich in der Iteration aktualisierten Funktionen in diesen Iterations-Branch und erstellen neue Dokumente für neue Funktionen direkt im Iterations-Branch. Der Vorgang hier ist vollständig konsistent mit der Verwendung von Iterations-Branches für die API-Dokumentation.
Da wir einen Schutz für den Haupt-Branch eingerichtet haben, sind direkte Änderungen am Dokumentinhalt im Haupt-Branch nicht erlaubt. Dies bedeutet, dass Sie Inhalte in veröffentlichten Dokumentationen, die Benutzer direkt sehen können, nicht manuell ändern können, was die Produktdokumentation stabiler macht und Situationen reduziert, in denen zufällige Änderungen zu fehlerhaften Inhalten führen, die von Benutzern gesehen werden.
2. Den schönen Markdown-Editor verwenden, um jedes Dokument zu schreiben
Produktmanager werden Markdown verwenden, um Dokumentationen zu schreiben, die in der aktuellen Iteration innerhalb des Iterations-Branch aktualisiert werden müssen. Die Markdown-Funktionalität von Apidog ist sehr leistungsstark, mit verschiedenen visuellen Komponenten, die per Klick viele komplexe Stile mit geringer Einstiegshürde einfügen können, sodass Sie mühelos schöne Artikel schreiben können, ohne zusätzlichen Aufwand.
Zusätzlich zur allgemeinen visuellen Einfügung im MD-Stil hat Apidog die folgenden speziellen Funktionen hinzugefügt:
- Projekt-APIs/Dokumente einfügen, wodurch Dokumente miteinander verknüpft werden können, um Referenzketten mit nahtloser Navigation zu bilden, was Lesern ein reibungsloseres Erlebnis bietet und die Bedürfnisse und Probleme der Leser besser löst – dies ist eine sehr wichtige Funktion.
- Umfangreiche Funktionen zum Einfügen von Ressourcen bereitstellen, wie Icons, Hervorhebungsblöcke, Tabellen, Schritte, Mermaid, Videos usw., sodass Sie keine Zeit damit verbringen müssen, selbst Ressourcen zu suchen oder die MD-Stilsyntax zu lernen, um Dokumente besser aussehen zu lassen.
3. Produkt-/Operations-Kollegen arbeiten zusammen, um Dokumente zu polieren
Nachdem Produktmanager die erste Version der Dokumente im Iterations-Branch geschrieben haben, übergeben sie die Dokumente an Operations-Kollegen, um sie aus der Benutzerperspektive zu lesen und Verbesserungsvorschläge zur Überarbeitung zu machen, um die Dokumentenqualität, Klarheit und Benutzerfreundlichkeit zu verbessern.
Dies war früher der zeitaufwändigste und mühsamste Teil, der eine gegenseitige Zusammenarbeit beider Seiten erforderte, wobei eine Partei ihre Ideen erklärte und spezifische Änderungsvorschläge für bestimmte Teile machte; dann die andere Partei die Änderungen entgegennahm, verstand und tatsächlich vornahm. Während des Hin- und Her-Prozesses gab es oft verschiedene Probleme wie Missverständnisse, falsche Änderungen und Inhaltsunterschiede zwischen Dokumentversionen, was zu einer sehr geringen Effizienz führte.
Mit Apidog können nun beide Seiten direkt Änderungen in den Dokumenten vornehmen, wobei Echtzeit-Nachrichtenbenachrichtigungen an den IM gesendet werden, wenn Änderungen vorgenommen werden, was es anderen ermöglicht, sofort das Dokument zu betreten und spezifische Änderungen leicht zu sehen, was die Effizienz der Zusammenarbeit erheblich verbessert. Hier sind die spezifischen Schritte:
- Produktmanager erstellen die erste Version der Dokumente. Nachdem das Operationspersonal die Benachrichtigung gesehen hat, lesen sie das Dokument und nehmen direkt Änderungen an Inhalten vor, die sie in diesem Dokument ändern möchten.
- Änderungen lösen beim Speichern automatisch Benachrichtigungen aus, die Änderungsnachrichtenkarten an die vorkonfigurierte IM-Gruppe senden. Nachdem Gruppenmitglieder die Änderungsübersichts-Nachrichtenkarten gesehen haben, können sie auf den Benachrichtigungslink klicken, um mit einem Klick das relevante Dokument zu betreten.
- Über die Änderungshistorie können Unterschiede durch Auswahl der aktuellen Version und der Originalversion verglichen werden, um die Änderungen der anderen Partei leicht einzusehen und zu entscheiden, wie das Dokument angepasst werden soll. Sie können wählen, Vorschläge nicht anzunehmen und zur Originalversion zurückzukehren, oder Änderungen anzunehmen und die neueste Version beizubehalten.
Produkt- und Operations-Teams wiederholen die oben genannten Schritte, bis der Dokumentinhalt überarbeitet und eine von allen genehmigte Version festgelegt ist.
4. Vorbereitung und Überprüfung vor der offiziellen Dokumentenveröffentlichung
Um sicherzustellen, dass der Inhalt und die Produkt-Screenshots in Dokumenten vollständig mit dem übereinstimmen, was Benutzer zugreifen können, empfehlen wir, Screenshots in der Produktionsumgebung des Produkts aufzunehmen. Dies ermöglicht auch die Überprüfung, ob neue Funktionen, die in der Produktionsumgebung eingeführt wurden, ordnungsgemäß funktionieren. Nachdem das Operationspersonal neue Funktionen online verwendet und Screenshots gemacht hat, fügen sie diese den Artikeln hinzu.
Die Operations bestätigen die abgeschlossenen Inhaltsdokumente aus dieser Iteration, wählen sie aus und reichen eine MR-Anfrage ein, um sie in den Haupt-Branch zu mergen.
Der Operationsmanager oder andere Projektadministratoren überprüfen den zu veröffentlichenden Dokumentinhalt, bestätigen dessen Korrektheit und wählen dann das Mergen in den Haupt-Branch.
Nachdem das Mergen abgeschlossen ist, können Benutzer, wenn sie auf veröffentlichte Dokumente zugreifen, den neuesten Inhalt sehen, der in den Haupt-Branch gemergt wurde.
Weitere Vorteile
Zusätzlich zu den bereits vorgestellten Funktionen bietet Apidog auch die folgenden Funktionen im Bereich der Dokumentenveröffentlichung, um jedem dabei zu helfen, Produktdokumentationsseiten zu erstellen, die seinen Bedürfnissen besser entsprechen.
1. Gesamtstile der Dokumentationsseite festlegen, die zum Produkt-/Unternehmensstil passen
Sie können den Gesamtstil der veröffentlichten Dokumentationsseite festlegen, wodurch der Stil der gesamten Website besser zum Ton Ihres Unternehmens passt und weitere verwandte Ressourcen und Links zu Unternehmensinhalten hinzugefügt werden, um den Benutzern ein besseres Erlebnis zu bieten.
Die Hilfedokumentation von Apidog hat ihr eigenes Logo und einige Apidog-bezogene Ressourcenlinks festgelegt. Oben links befindet sich das Firmenlogo, oben rechts verschiedene unternehmensbezogene Ressourcenlinks, und die offene API-Dokumentation, die Entwicklern wichtiger ist, ist ebenfalls in der Produktdokumentation festgelegt:
2. Wartungsfreies Veröffentlichungserlebnis
In Apidog müssen Sie nur auf die Schaltfläche "Veröffentlichen" in der Funktion zur Dokumentenveröffentlichung klicken, um die gesamte Dokumentation mit einem Klick für Ihre Benutzer lesbar im Internet zu veröffentlichen. Apidog stellt offiziell Domains zur Verfügung, die jeder nutzen kann, was viel Wartungsaufwand spart.
Wenn Sie die Dokumentation natürlich mehr wie die Website Ihres eigenen Unternehmens gestalten möchten, bieten wir auch eine benutzerdefinierte Domain-Funktionalität an, die es Ihnen ermöglicht, die Domain Ihres eigenen Unternehmens für den Zugriff auf die Dokumentation zu verwenden.
Sie können auch ganz einfach die reguläre Suche, die Algolia-Volltextsuche einrichten, GA integrieren, Weiterleitungen festlegen und andere erweiterte Funktionen auf veröffentlichten Produktdokumentationsseiten mit einfachen Operationen einrichten. Diese Konfigurationen erfordern keine ausreichenden technischen Fähigkeiten der Bediener – sie können einfach durch Befolgen der Benutzeroberflächenanleitung und Hilfedokumentation eingerichtet werden.
3. Mehrere SEO-freundliche Einstellungen
Apidog generiert automatisch vernünftige Slugs für veröffentlichte Dokumentationsseiten basierend auf Grundeinstellungen, um Benutzern einen besseren Zugriff und eine bessere Freigabe zu ermöglichen.
Wenn Sie natürlich fortgeschrittenere SEO-Anforderungen haben, unterstützt es auch benutzerdefinierte Slugs, Metadaten und verschiedene andere Inhaltseinstellungen für jedes einzelne Dokument.
Fazit
Das Obige ist die spezifische Praxis der Verwendung von Apidog für die Pflege der Produktdokumentation.
Zusätzlich zu den oben genannten Inhalten können wir auch Produkthilfe-Dokumentationen, Entwickler-Dokumentationen und API-Dokumentationen in einem Stil pflegen und alle miteinander verknüpfen, um ein noch besseres Benutzererlebnis zu bieten. Wenn Ihre tatsächliche Situation geeignet ist, laden wir Sie ein, diese Praxis auszuprobieren und sie anderen Kollegen zu empfehlen. Wir hoffen, dass dies einige Effizienz- und Qualitätsverbesserungen für Ihre Arbeit an der Produktdokumentation mit sich bringen kann.