So bauen Sie eine SEO-freundliche Support-Wissensdatenbank auf: Der vollständige Leitfaden für eine skalierbare Dokumentationslösung

Veröffentlicht: 2016-10-26

Sobald die Benutzerbasis Ihres Startups wächst, wird der Support zu einem grundlegenden Bestandteil Ihres Unternehmens. Die Einrichtung einer soliden Wissensdatenbanklösung ist eine wichtige langfristige Investition, die sich hoffentlich auszahlt, wenn sie richtig gemacht wird, indem sie den Supportaufwand reduziert, die SEO-Reichweite Ihrer Website erweitert und neue Leads generiert, die sonst nicht gelandet wären.

Dies ist eine umfassende und technische Schritt-für-Schritt-Anleitung für Entwickler. Wenn Sie kein Entwickler sind, sollten Sie diesen Artikel wahrscheinlich an Ihren CTO senden. Er/sie wird es dir danken.

TL;DR: Wir haben endlich unsere halbstatische, markdownbasierte Wissensdatenbank für unsere Monetarisierungsplattform Freemius mit WordPress erstellt und veröffentlicht. Ich teile hier das komplette Kochbuch unserer Forschung; warum wir WordPress gegenüber SaaS-Lösungen und statischen Generatoren wählen; wie wir es gemacht haben (einschließlich aller Codeanpassungen und Konfigurationen auf Serverebene), was wir gelernt haben und wie Sie diesen Prozess replizieren können, um wertvolle Zeit zu sparen und Ihre eigene blitzschnelle, skalierbare, nachhaltige, sichere und halbwegs Statische KB (Knowledge Base) für Ihr eigenes Plugin, Design oder jedes andere digitale Produkt.

Dieser 15-minütige Leitfaden spart Ihnen 44 Stunden (wir haben Zeiterfassung verwendet) für Recherche, Anpassung, Tests und Optimierung. Wenn Sie noch nicht in der Phase der Einrichtung Ihres eigenen Dokumentationszentrums sind, speichern Sie diese Seite einfach mit einem Lesezeichen und kommen Sie zu gegebener Zeit wieder.

Sind Sie bereit? Auf geht's.

Motivation
Worauf sollten Sie bei einer Dokumentationslösung achten?
1. Skalierbar und langlebig
2. Benutzerfreundliches Backoffice
3. Nachhaltig
4. SEO-optimiert
5. Markenkompatibel
Die Wahl der richtigen Dokumentationsplattform ist schwierig!
- Wissensdatenbank Software as a Service
- Statische Wissensdatenbanken
- Von WordPress unterstützte Wissensdatenbanken
Warum wir uns nicht für Help Scout Docs oder eine andere SaaSy-Wissensdatenbank entschieden haben
Warum wir WordPress gegenüber Generatoren für statische Websites für unsere Wissensdatenbank wählen
Warum wir das weDocs WordPress Plugin für unsere Wissensdatenbank wählen?
Installation und Anpassung der weDocs-Dokumentationslösung
- Breadcrumbs-Rich-Snippets-Metadaten hinzufügen
- Anpassen der URL-Struktur der Wissensdatenbank (Permalinks)
- Hinzufügen einer hübschen Homepage zur weDocs-Wissensdatenbank
- WeDocs mobilfreundlich / reaktionsschnell machen
Verwenden von Markdown anstelle von HTML Rich Editing
- Auswählen und Installieren eines Markdown-WordPress-Plugins
- Hinzufügen von YouTube- und Vimeo-Markdown-Unterstützung
- Hinzufügen von Nice Callouts Shortcodes Support
- Hinzufügen von SyntaxHighlighter für hübschen Code
Wie wir unsere WordPress-Wissensdatenbank superschnell gemacht haben?
- Festplattenberechtigungen hinzufügen
- Caching aktivieren
- Caching auf Serverebene konfigurieren
- CDN hinzufügen
Wie haben wir die KB-Suche angepasst, um zwischengespeicherte Daten bereitzustellen?
Wie haben wir unsere WordPress-Wissensdatenbank gesichert?
Jetzt du

Motivation

Dokumentation war seit den Anfängen von Freemius immer auf unserer TODOs-Liste. Wenn sich das Produkt jedoch in einem frühen Stadium befindet, macht es keinen Sinn, es zu überstürzen und zu dokumentieren. Der Fokus sollte auf der Validierung von Annahmen und schnellen Iterationen liegen, bis Sie zu einem zufriedenstellenden Produkt-Market-Fit kommen. Wir haben Freemius vor ungefähr anderthalb Jahren gestartet, und wir hatten endlich das Gefühl, dass es an der Zeit war, der Dokumentation Priorität einzuräumen.

Worauf sollten Sie bei einer Dokumentationslösung achten?

Bevor ich in eine Lösung stürzte, wollte ich eine Art Plan haben. Daher habe ich folgende Anforderungsliste erstellt:

Skalierbar und langlebig

Wie jede andere webbasierte Lösung muss sie in der Lage sein, mit unserem Datenverkehr zu skalieren und dabei die gleiche Leistung beizubehalten. Es MUSS auch weiterhin mühelos sein, Antworten zu finden, wenn die Wissensdatenbank über ein Dutzend Artikel hinauswächst. Mit anderen Worten – gute Suche!

Benutzerfreundliches Backoffice

Das Hinzufügen und Bearbeiten von Dokumentationsartikeln sollte für jedes Teammitglied einfach sein, unabhängig davon, ob es sich um Entwickler handelt oder nicht.

Nachhaltig

Nichts hält ewig. Designtrends ändern sich und die Technologie entwickelt sich ständig weiter. Es sollte daher relativ einfach sein, die Benutzeroberfläche der Wissensdatenbank zu ändern und in extremen Fällen die Daten problemlos zu exportieren und insgesamt auf ein anderes System zu migrieren.

SEO-optimiert

Dokumentation ist Inhalt. Im Gegensatz zu Ihren Blogbeiträgen konzentriert sich die Knowledge Base-Dokumentation ausschließlich auf Ihr Produkt. Ihre Schlüsselwörter. Es ist eine großartige Möglichkeit, Ihre SEO-Autorität bei allem, was Sie verkaufen, zu stärken.

Wenn Benutzer nach etwas suchen, ist es außerdem üblich, sofort eine Suchmaschine zu verwenden. Es ist einfach einfacher, als Ihre Website zu öffnen, nach dem Link Knowledge Base / Help Center / Docs zu suchen und erst dann nach einer Lösung zu suchen. Stellen Sie daher besser sicher, dass Ihre Dokumentationsinhalte für Suchmaschinen sichtbar und für sie optimiert sind, insbesondere für Google, wenn Sie auf den englischsprachigen Markt abzielen.

Markenkompatibel

Das Look & Feel der Knowledge Base sollte zur Designsprache und zum Branding unseres Unternehmens passen. Dazu gehören Farben, Schriftarten, Kopf- und Fußzeilenstil usw.

Die Wahl der richtigen Dokumentationsplattform ist schwierig!

Ich folgte meinem natürlichen Entdeckungsfluss und bat Google um Rat. Diesmal war Google nicht hilfreich. Die Suchergebnisse waren überwältigend. Nicht nur, dass es so viele Optionen auf dem Markt gibt, die Lösungen sind von Natur aus unterschiedlich.

Google war nicht hilfreich. Es gibt so viele Optionen auf dem Markt und die Lösungen sind von Natur aus unterschiedlich.Tweet

Wissensdatenbank Software as a Service

Es gibt ausgewiesene Wissensdatenbank-Softwarelösungen, die von Helpdesk-Unternehmen wie Help Scout Docs und Zendesk Help Center betrieben werden.

Statische Wissensdatenbanken

Statische Site-Generatoren werden immer beliebter. Wenn Sie mit dem Konzept nicht vertraut sind, ist die allgemeine Idee, dass die meisten Websites ziemlich statisch sind (einschließlich Ihres WordPress-Blogs) und es keinen wirklichen Grund gibt, einen auslaugenden Backend-Stack wie WordPress / PHP / MySql auszuführen. Verlagern Sie stattdessen das schwere Heben auf eine Pre-Deployment-Engine, die statische HTML-Seiten generiert, die auf CDNs gehostet werden können, ohne Ihre Server zu berühren. Es ist kosteneffizient, skalierbar und sicher.

Es gibt Hunderte von Generatoren und Engines wie Jekyll und Hugo sind in der Community der Hardcore-Entwickler sehr beliebt (aus gutem Grund!).

Von WordPress unterstützte Wissensdatenbanken

Ich habe über 20 kostenlose Wissensdatenbank-Plugins im WordPress.org-Repository gefunden, ein weiteres Dutzend kostenpflichtiger Dokumentations-Plugins auf CodeCanyon und Google und ein weiteres Dutzend Help-Center-Designs.

Verwirrt sein? Ich habe definitiv ¯\(°_o)/¯ gemacht

Wie Sie sehen können, viel zu viele Optionen. Ich beschloss, eine andere Strategie auszuprobieren – Leute um eine Empfehlung zu bitten, deren Meinung ich vertraue. Ich bin Mitglied einer Facebook-Gruppe namens Selling WordPress Products, zu der viele meiner Freunde und führenden WordPress-Produktexperten gehören. Ich bin mir ziemlich sicher, dass 90 % von ihnen vor mir die gleiche Herausforderung gemeistert haben, also war es definitiv einen Versuch wert.

Bevor ich meine Frage hochgeladen habe, habe ich etwas gesucht und einen Thread aus dem Jahr 2015 gefunden, der von Jean Galea von WP Mayor gestartet wurde und genau dieselbe Frage stellt:

Fantastisch! Ich dachte mir. Und dann fing ich an, die Antworten zu lesen …

Adrian Labos verwendet Zendesk Help Desk
Pippin Williamson (Pippin Plugins) und Adam Pickering (Astoundify) verwenden Help Scout Docs
Phil Derksen verwendet WordPress mit dem KnowHow-Thema
Dejan Markovic (Hype Social) verwendet WordPress mit dem weDocs-Plugin
Devin Walker (WordImpress) verwendet WordPress mit CPT und dem ACF-Plugin.
Ahmad Awais, der das DocPress-Theme erstellt hat, sagt, dass „das Pflegen einer Dokumentseite mit WordPress ineffizient geworden ist, wenn die Anzahl der Produkte wächst“, und jetzt baut er eine statische Wissensdatenbank mit der Jade-Vorlagen-Engine auf.
Tom Hemsley (Mega Menu Plugin) empfahl, WordPress mit dem Heroic Knowledge Base-Plugin zu verwenden.
Es gab weitere drei Antworten zu zusätzlichen WordPress-Plugins von ihren Autoren, die Teil der Gruppe sind.

Wie Sie sehen können, gibt es einfach keinen Konsens. Leider war dies nicht sehr hilfreich.

Verdammt – es ist Zeit für etwas Recherche…

TIPP: Als Randbemerkung, wenn Sie ein Produktmensch im WordPress-Bereich sind, empfehle ich Ihnen dringend, sich für diese Gruppe zu bewerben.

Abonnieren Sie und holen Sie sich eine kostenlose Kopie unserer

WordPress Plugin Geschäftsbuch

Genau, wie man ein florierendes WordPress-Plugin-Geschäft in der Abonnementwirtschaft aufbaut.

Danke fürs Abonnieren!

- wir haben gerade Ihr Exemplar von 'The WordPress Plugin Business Book' an gesendet .

Haben Sie einen Tippfehler in Ihrer E-Mail? Klicken Sie hier, um die E-Mail-Adresse zu bearbeiten und erneut zu senden.

Warum wir uns nicht für Help Scout Docs oder eine andere SaaSy-Wissensdatenbank entschieden haben

Ich bin ein Fan von Help Scout und wir verwenden sie für unser Support-Ticketing-System. Tatsächlich bin ich mit den Gründern befreundet. Im Jahr 2011 arbeiteten wir Schreibtisch für Schreibtisch und hingen 4 Monate lang zusammen, während wir am Accelerator-Programm von Techstars in Boston teilnahmen. Das war damals, als Help Scout nur aus Denny, Jared und Nick bestand.

Docs ist eine ziemlich solide Dokumentationslösung und wahrscheinlich der einfachste und schnellste Weg. Es ist auch überraschend anpassbar. Aber wie die anderen SaaS-Plattformen hat es SEO-Mängel.

1. Das Einrichten einer Wissensdatenbank oder anderer Inhalte in einem Unterverzeichnis ist in Bezug auf das Suchranking immer noch deutlich besser als auf einer Subdomain. Rand Fishkin, der Gründer von MOZ (dem weltweit führenden SEO-Unternehmen), hat ein großartiges Video aus dem Jahr 2015 mit echten Anwendungsfällen, in denen dieses Thema diskutiert wird.

Leider gibt es aufgrund der Funktionsweise von DNS-Zonendateien keine Möglichkeit, einen CNAME für ein Unterverzeichnis einzurichten.

Um sicherzustellen, dass ich keine Problemumgehung verpasst habe, habe ich das Support-Team von Help Scout kontaktiert und hier ist die Antwort, die ich erhalten habe:

„Ich komme nur ungern mit schlechten Nachrichten, aber es gibt keine Möglichkeit, Dokumente in einem Unterverzeichnis zu haben. Wir haben eine API für Docs, mit der Sie Ihre Website exportieren und selbst hosten können, aber Sie müssten einen Teil des Aussehens und der Funktionalität neu erstellen: http://developer.helpscout.net/docs-api/
Ich fürchte, dies wäre die einzige Lösung, wenn Sie immer noch Docs verwenden und es als Unterverzeichnis haben möchten.

2. Ich habe die anderen Lösungen aus dem vorherigen Grund nicht überprüft, aber insbesondere Help Scout Docs enthält keine Rich-Snippets-Metadaten für Breadcrumbs und Suche.

So sieht ein Ergebnis von Help Scout Docs auf Googles SERP (Suchmaschinen-Ergebnisseite) aus:

Hier ist das Ergebnis einer Seite mit Breadcrumbs-Rich-Snippets-Metadaten:

Und hier ist das Ergebnis einer Seite mit Rich Snippets-Such-Metadaten:

Ich werde nicht weiter auf dieses Thema eingehen, aber im Allgemeinen helfen Rich Snippets-Metadaten der Suchmaschine, den Inhalt Ihrer Website und ihre Struktur besser zu verstehen. Die weltweit führenden Suchmaschinen: Google, Yahoo und Bing; kann diese Daten in visuelle Darstellungen übersetzen, die die Such-CTR (Click-Through-Rate) erhöhen. Unterm Strich – Sie erhalten mehr Verkehr.

Ich habe auch Chris Mooney angepingt, einen Mitbegründer von HeroThemes, einem Unternehmen, das sich allein auf Wissensdatenbanklösungen konzentriert, und er bestätigte, dass SEO einer der Hauptgründe ist, warum Kunden zu ihrer lokalen Dokumentationslösung migrieren.

Nur um die Bedeutung des SEO-Werts zu betonen, den Sie aus einer gut geschriebenen Dokumentation ziehen können, möchte ich eine kurze Geschichte erzählen. 2011 traf ich mich mit Elad Eran, VP Customer Solutions bei WiX. Eran erklärte stolz, dass ihre Wissensdatenbank-Software und ihre Support-Foren einer der Hauptkatalysatoren sind, die WiX geholfen haben, einen hohen Rang bei Google zu erreichen und kostenlosen, qualitativ hochwertigen organischen Traffic zu erhalten.

Wissensdatenbank-Software und Support-Foren sind einer der wichtigsten Katalysatoren, die WiX geholfen haben, bei Google einen hohen Rang einzunehmen und kostenlosen, qualitativ hochwertigen, organischen Traffic zu erhalten.Tweet

Wenn es gut für WiX ist, sollte es auch gut für uns sein

Warum wir WordPress gegenüber Generatoren für statische Websites für unsere Wissensdatenbank wählen

Die Hauptvorteile einer statischen Konfiguration mit einer Engine wie Jekyll sind Geschwindigkeit, Skalierbarkeit und Sicherheit.

Können wir die mit WordPress bekommen? Die Antwort ist – fast.

Da Dokumentationsseiten statisch sind (mit Ausnahme der Suche), können wir problemlos eines der Dutzenden kostenloser WordPress-Caching-Plugins installieren, Nginx so konfigurieren, dass die zwischengespeicherten Dateien direkt von der Festplatte bereitgestellt werden, während die WordPress-Engine übersprungen wird, und auch einen kostenlosen CDN-Dienst wie verwenden CloudFlare, um unsere Dateien in verschiedenen Rechenzentren auf der ganzen Welt zu verteilen. Es mag komplex klingen, aber das ist es wirklich nicht, und ich werde alles bald erklären.

Dadurch wird unser Dokumentations-Frontend absolut statisch. Es lässt sich hervorragend skalieren und ist superschnell (weil es statisch ist). W00t! W00t!

In Bezug auf die Sicherheit ist nichts perfekt. Aber wir können einige grundlegende Vorsichtsmaßnahmen treffen, indem wir ein paar kostenlose Plugins und einige Konfigurationen auf Serverebene verwenden, die die Wahrscheinlichkeit eines Angriffs um 99,9 % reduzieren. Ich werde das gleich ausführlich besprechen, einschließlich aller Zutaten.

Andererseits waren die Nachteile des statischen Ansatzes für unser Team:

Als Team müssen wir uns neue technische Fähigkeiten aneignen, eine zusätzliche Entwicklungsumgebung einrichten und einen kontinuierlichen Bereitstellungsprozess einrichten, um sicherzustellen, dass das Hinzufügen oder Bearbeiten von Dateien kein Eingreifen eines Entwicklers erfordert. Es ist auf jeden Fall machbar, aber es braucht Zeit.
Die Suche ist (meistens) eine dynamische Funktion. Wenn wir also statisch werden, müssen wir eine RESTful-API implementieren oder einen Suchdienst eines Drittanbieters wie Algolia integrieren. Ein weiteres Kopfzerbrechen.
Die Versionskontrolle ist kein CMS. So sehr ich GitHub und BitBucket liebe, könnten sie für nicht technisch versierte Leute beängstigend sein. Auch wenn alle unsere Teammitglieder in ihrem Hintergrund Entwickler sind, wird sich dies wahrscheinlich in Zukunft ändern.

TIPP: Erwähnenswert ist, dass ich während meiner Recherche ein raffiniertes Projekt namens Prose.io gefunden habe, das eine einfache WYSIWYG-Inhaltsbearbeitung von GitHub- und BitBucket-Dateien bietet.

Zusammenfassend lässt sich sagen, dass wir die meisten Vorteile statischer Websites nutzen können, ohne die Flexibilität von WordPress zu verlieren, den benutzerfreundlichen CMS-Editor beibehalten und eine Echtzeitbearbeitung ohne einen kontinuierlichen Bereitstellungsprozess erhalten.

Warum wir das weDocs WordPress Plugin für unsere Wissensdatenbank wählen?

Wie bereits erwähnt, hatte ich mindestens 30 WordPress-Plugins und -Themen für Wissensdatenbanken gesehen.

Da wir ein Startup betreiben, ist es nicht möglich, alle zu bewerten. Versuchen wir es also mit der Eliminierung.

Themen der Wissensdatenbank sind da!

Wir haben uns entschieden, keine Dokumentationsthemen zu verwenden, da die meisten von ihnen das standardmäßige post und die category für die Dokumentationsartikel verwenden. Diese Lösung kann funktionieren, wenn Sie eine dedizierte WordPress-Instanz nur für Ihre Knowledge Base-App einrichten. Wenn Sie Ihre gesamte Website auf derselben WordPress-Installation haben möchten, einschließlich Ihres Blogs, können und werden die Dinge aufgrund der Mischung von Inhaltstypen chaotisch werden.

Juhu – wir haben jetzt nur noch 20 weitere Plugins zum Testen…

Ich habe vier verschiedene kostenlose Plugins getestet:

Wissensdatenbank CPT
WP-Wissensdatenbank
WP-Hilfe
weDocs

Ziemlich schnell stellte ich fest, dass sie alle WordPress CPT (Custom Post Types) und benutzerdefinierte Taxonomie für Tags und Kategorien nutzen. Der wichtigste und einzige signifikante Unterschied liegt in der Hierarchie der Datenstruktur.

Knowledge Base CPT und WP Knowledge Base sind flach. Wie bei Blogbeiträgen gibt es Kategorien, Tags und Artikel. Es gibt keine Möglichkeit, einen Artikel mit einem übergeordneten Artikel zu verknüpfen.

Die Struktur einer Wissensdatenbank mit diesen Plugins besteht also aus Kategorien als Abschnitte und Beiträge als Dokumente.

 Kategorie 1
↳ Dok 1
↳ Dok 2

Kategorie 2
↳ Dok 3
↳ Dok 4

Der Vorteil dieser Struktur besteht darin, dass Sie ein Dokument mehreren Kategorien zuordnen und es in mehreren Abschnitten anzeigen lassen können.

 Kategorie 1
↳ Dok 1
...
Kategorie 2
↳ Dok 3
↳ Dok 1

Auf der anderen Seite ähnelt die Artikelstruktur von WP Help und weDocs Seiten. Jedes Dokument kann jedem anderen Dokument als übergeordnetes Dokument zugeordnet werden. Aber es kann nur mit einem übergeordneten Element verknüpft werden (nicht wie mit einer Kategorie).

 Dok 1
↳ Dok 2
↳ Dok 3
↳ Dok 4
↳ Dok 5
↳ Dok 6

Diese Struktur hat zwei Vorteile:

Es ist strukturierter. Es zwingt Sie zu überlegen, wo genau der geeignetste Ort ist, um den Dokumentationsartikel hinzuzufügen.
Kategorien haben keine bestimmte „Reihenfolge“. Daher gibt es keine sofort einsatzbereite Möglichkeit, Kategorien so zu organisieren, wie dies bei Beiträgen mit der Eigenschaft menu_order möglich ist.

Die oben genannten Gründe waren genau der Grund, warum wir uns für die hierarchischen Plugins entschieden haben.

Toll – jetzt weiß ich, welche Art von Datenstruktur wir für unsere Dokumentation brauchen.

Ich verbrachte dann Zeit damit, über zwei Premium-Plugins zu lesen – wpDocs (die Pro-Version der WP Knowledge Base) und Heroic Knowledge Base. Beide sehen optisch beeindruckend aus, aber…

Ich konnte keinen sinnvollen Unterschied zwischen diesen beiden Premium-Plugins und den kostenlosen Plugins feststellen.
Beide Plugins verwenden die flache Datenstruktur, auf die wir uns entschieden haben.

Also ja – es gab wahrscheinlich weitere 10 Plugins, die ich mir nicht einmal angesehen habe, aber das Muster war klar.

Wir haben uns aus mehreren Gründen für weDocs statt WP Help entschieden:

Die Drag & Drop-Benutzeroberfläche für die Administratoreinstellungen von weDocs ist modern, benutzerfreundlich und optisch ansprechend.
WP Help enthält keine benutzerdefinierte Taxonomie für die Dokumente. Das bedeutet, dass Kategorien und Tags nicht sofort geliefert werden.
WP Help unterstützt überhaupt keine Breadcrumbs.
weDocs wird mit einer Reihe von benutzerdefinierten Vorlagen geliefert, die die Dokumentation sofort gut aussehen lassen (offensichtlich erforderte eine gewisse Anpassung der Benutzeroberfläche).
weDocs hat einen kontinuierlichen UI-Flow. Am Ende jedes Artikels können Sie zum nächsten in der Zeile navigieren.

Kommen wir zum spaßigen Teil – der Umsetzung…

Installation und Anpassung der weDocs-Dokumentationslösung

Um zu beginnen, laden Sie weDocs direkt aus dem WordPress.org-Repo herunter und installieren Sie es:
https://wordpress.org/plugins/wedocs/

Jetzt ist es an der Zeit, ein paar Anpassungen vorzunehmen:

Breadcrumbs-Rich-Snippets-Metadaten hinzufügen

Da wir das eigentliche Plugin (wenn möglich) nicht ändern wollten, haben wir das weDocs-Templating und die functions.php des Themes verwendet, um das Standard-Breadcrumbs-Rendering zu überschreiben.

Kopieren /wedocs/templates/single-docs.php nach /your-theme/wedocs/single-docs.php .
Fügen Sie der Datei functions.php des Themes den folgenden Code hinzu:
Öffnen /your-theme/wedocs/single-docs.php und ersetzen Sie den Aufruf von wedocs_breadcrumbs() durch freemius_wedocs_breadcrumbs() .
Da wir für eine bessere Semantik auch die HTML-Struktur der Breadcrumbs in eine ungeordnete Liste ( <ul> ) geändert haben, fügen Sie Ihrem Design den folgenden SASS-Code hinzu:

Um die Rich Snippets zu vervollständigen, müssen Sie den folgenden Code zu Ihrem <body> -Tag hinzufügen:

<body<?php if ('docs' === get_post_type()){     echo ' itemscope itemtype="http://schema.org/WebPage"'; } ?>>

Anpassen der URL-Struktur der Wissensdatenbank (Permalinks)

weDocs wird mit der folgenden Standard-Permalink-Struktur ausgeliefert:
your-site.com/wordpress-root/docs/

Wir wollten unsere Dokumentation auf freemius.com/help/documentation/ haben, was in SEO bei der Suche nach Dokumentation besser ranken sollte. Wir wollten auch die „Hilfe“-Seite beibehalten, um in Zukunft ein Hilfezentrum hinzuzufügen, damit wir URL-Strukturen wie /help/faq/ für eine FAQ-Seite und /help/forum/ für ein Forum verwenden können.

Wir könnten dies leicht erreichen, indem wir die Rewrite-Regeln des docs CPT im Code des Plugins ändern. Da wir aber vermeiden wollen, den Code des Plugins zu ändern, haben wir einen Weg gefunden, dies indirekt in der Datei functions.php des Themes zu tun:
Zusätzlich haben wir Unterstützung für Artikelauszüge (wir brauchen das für die nächste Anpassung), Dokumentautor, benutzerdefinierte Felder und Seitenattribute hinzugefügt. Wichtig: weDocs ist standardmäßig für Multi-Produkt-Wissensdatenbanken strukturiert. Wenn Sie also die Struktur von /help/documentation/ haben möchten, stellen Sie sicher, dass das Top-Level-Dokument, das Sie im Backoffice erstellen, Dokumentation heißt (Slug muss documentation sein).

Hinzufügen einer hübschen Homepage zur weDocs-Wissensdatenbank

Standardmäßig wird weDocs mit einem Shortcode ausgeliefert, der Ihnen helfen kann, eine Homepage zu erstellen, die so aussieht:

Es ist nicht schlecht, aber ich persönlich bevorzuge das von Help Scout Docs generierte Layout:

Es bietet eine kurze Beschreibung zu jedem Abschnitt und sieht für mich optisch ansprechender aus. Lassen Sie uns zunächst die PHP-Vorlagen erstellen, indem docs-header-main.php und docs-sections.php in den Ordner /your-theme/wedocs/ . Den Code finden Sie im folgenden Gist: https://gist.github.com/vovafeldman/adbf1c071a08b7565df11d709b2f1240 Wenn Sie in den Code der Datei docs-header-main.php , werden Sie feststellen, dass ich mich auch in die Suche eingeschlichen habe Snippets-Metadaten. Da der Artikel /help/documentation/ nun nur ein weiterer Artikel in der Knowledge Base ist, ist die Standardvorlage, die WordPress verwendet, /wedocs/single-docs.php . Daher müssen wir das folgende Code-Snippet am Anfang dieser Datei hinzufügen, um die neuen Abschnittsvorlagen zu laden, wenn das übergeordnete Element des Artikels nicht festgelegt ist:

if ( empty( $post->post_parent ) ) {
  wedocs_get_template_part( 'docs', 'header-main' );
  wedocs_get_template_part( 'docs', 'sections' );

  return;
}

WeDocs mobilfreundlich / reaktionsschnell machen

Leider wird weDocs nicht mit responsiven CSS-Regeln ausgeliefert. So sieht es in der Knowledge Base von weDevs (den Entwicklern von weDocs) aus:

Ich werde nicht in das CSS eintauchen, aber im Allgemeinen haben wir Medienabfragen hinzugefügt, die:

Verstecke die Semmelbrösel.
Machen Sie den Inhalt in voller Breite mit einer schönen Polsterung.
Die Navigationsseitenleiste und die Suche nach unten verschoben, direkt vor die Fußzeile.

Hier ist das Ergebnis:

Und so sieht die Abschnittsseite aus:

Toll! Wir sind mit der weDocs-Anpassung fertig.

Verwenden von Markdown anstelle von HTML Rich Editing

Eine der anfänglichen Anforderungen der KB war Nachhaltigkeit – die Möglichkeit, das Design und möglicherweise eine Plattform (erinnern Sie sich?) leicht zu ändern. Die Verwendung von HTML Rich Content Editing ist ein zweischneidiges Schwert. Einerseits ist es extrem flexibel und gibt Ihnen die Freiheit, den Inhaltsstil nach Ihren Wünschen anzupassen. Auf der anderen Seite erlaubt dieser Mangel an Struktur jedem Inhaltsautor, zu tun, was er will. Dies ist nicht nachhaltig, macht Designänderungen komplex und die Migration noch schwieriger. Verwenden Sie zum Beispiel <strong> vs. <b> . Oder verwenden Sie <table> vs. <div> -basierte Tabellen. Das sind syntaxbezogene Entscheidungen, und jede Person hat ihren einzigartigen Schreibstil.

Worauf sich Content-Autoren wirklich konzentrieren sollten, sind Inhalt und Semantik, nicht Design.

Es gibt viele Auszeichnungssprachen mit Klartext-Formatierungssyntax, obwohl Markdown die natürliche Wahl war, da es von Giganten wie GitHub, Atlassian und WordPress selbst weit verbreitet ist.

Auswählen und Installieren eines Markdown-WordPress-Plugins

Es gibt nur zwei Markdown-Plugins im WordPress.org-Repo, die mehr als 1.000 aktive Installationen haben. WP-Markdown und JP-Markdown. Ja, Jetpack hat auch ein Markdown-Modul, aber es war nicht sinnvoll, dieses „Monster“ nur für ein Modul zu installieren. Anfangs habe ich WP-Markdown installiert, weil es basierend auf den Screenshots die Möglichkeit hatte, einfach auszuwählen, welche Beitragstypen Markdown unterstützen. Leider hat das Plugin nicht funktioniert (das letzte Update war vor über 3 Jahren), sodass wir es letztendlich nicht verwendet haben. Dann habe ich JP Markdown installiert. Das Plugin hat funktioniert, hatte aber einige Dinge, die mir nicht gefallen haben:

Der Markdown wurde automatisch auf allen Beiträgen und Seiten aktiviert.
Die Markdown-Syntax wurde nicht beibehalten, sie wurde automatisch in formatiertes HTML konvertiert:

Dies ist schlecht, da die Daten als Rich-HTML und nicht als Markdown in der Datenbank gespeichert werden (das habe ich überprüft). Außerdem werden keine Einschränkungen für die Rich-HTML-Bearbeitung hinzugefügt. Wenn wir also in Zukunft auf ein anderes System migrieren möchten, gibt es keine Möglichkeit, den Markdown zu exportieren.

Dann habe ich den WP Markdown Editor gefunden, der das Markdown-Modul von Jetpack verwendet, und das war das, was wir letztendlich verwendet haben. Auch wenn wir noch ein paar Anpassungen vornehmen mussten:

Das Plugin deaktiviert bei der Aktivierung die Rich-Bearbeitung von allen Beiträgen und Seiten. Wir wollten die reichhaltige Bearbeitung nur auf unseren Dokumentationsseiten loswerden.
Das Plugin überschreibt den bestehenden Editor mit einem eigenen Markdown-Editor für alle Beiträge und Seiten. Auch das wollten wir nur auf unseren Dokumentationsseiten haben.

Sie können diese Änderungen hier sehen:
https://github.com/Freemius/wp-markdown-editor/commit/706bce0c23943c82d102c67a09e18dac32c66207

Sie können die gegabelte Version von hier herunterladen (nur ein paar winzige Änderungen):
https://github.com/Freemius/wp-markdown-editor

Dann haben wir eine kurze Funktion hinzugefügt, die docs CPT registriert, um die Markdown-Bearbeitung zu unterstützen, und die Registrierung von post und page aufhebt, um den HTML-Rich-Editor beizubehalten:

Schließlich mussten wir die standardmäßige Exportfunktion von WordPress so anpassen, dass der Markdown-Code und nicht der HTML-reiche Inhalt exportiert wird. Wir haben es geschafft, indem wir uns an den Filter the_content_export :
Großartig – unsere KB basiert auf Markdown und kann einfach exportiert werden.

Hinzufügen von YouTube- und Vimeo-Markdown-Unterstützung

Videos sind ein wesentlicher Bestandteil jeder Wissensdatenbank. Leider unterstützt Markdown keine Videos. Glücklicherweise macht WordPress das Hinzufügen von Shortcodes supereinfach und mit ein paar Zeilen Code. Wir haben unsere Markdown-Syntax erweitert, um das Hinzufügen von YouTube- und Vimeo-Videos zu unterstützen:

Als Bonus haben wir die Videogröße responsiv und mobilfreundlich gemacht und das Hinzufügen von Videos ist jetzt intuitiv und unkompliziert mit der Video-ID:
[youtube gj6aoYG4fUI]
[vimeo 185625717]

Hinzufügen von Nice Callouts Shortcodes Support

Die standardmäßige Markdown-Syntax unterstützt Blockzitate, enthält jedoch keine Semantik für verschiedene Callouts wie Tipps und Warnungen, die nicht obligatorisch, aber für eine gute Wissensdatenbank wichtig sind.

WordPress Shortcodes wieder zur Rettung

Und so sieht es im Frontend aus:

Wir haben das Präfix fs_ hinzugefügt, um potenzielle Konflikte mit Plugins zu vermeiden, die wir in Zukunft installieren könnten.

Hinzufügen von SyntaxHighlighter für hübschen Code

Weder WordPress noch WP Markdown Editor verfügen über eine Code-Syntax-Hervorhebung. Da Freemius eine Plattform für Entwickler ist und unsere Dokumentation mit Codebeispielen geliefert wird, war das Hinzufügen von Syntax-Highlighting entscheidend. Wir haben uns für SyntaxHighlighter Evolved entschieden, da es von Automattic unterstützt wird, genau wie das Markdown-Kernmodul von Jetpack, das vom WP Markdown Editor-Plugin verwendet wird. Ein Blick auf den Markdown-Rendering-Code zeigt, dass sie tatsächlich zusammen integriert sind:

$this->use_code_shortcode = class_exists( 'SyntaxHighlighter' );

Fantastisch! Rechts? Leider scheint nichts sofort einsatzbereit zu sein und der Code wurde falsch gerendert. Es hat die mehrzeiligen Markdown-Codeabschnitte durcheinander gebracht, indem Sonderzeichen in ihre entsprechenden HTML-Entitäten umgeleitet wurden. Es hat nicht nur den gerenderten Code auf dem Frontend „geknackt“, sondern auch eine Escape-HTML-Version der Codeteile des Markdowns in der Datenbank gespeichert. Und das ist schlecht für die Aufbewahrung von Inhalten und den möglichen Datenexport. Daher blieb uns nichts anderes übrig, als ein paar Änderungen am Code des Plugins vorzunehmen. Die genauen Änderungen seht ihr hier:
https://github.com/Freemius/wp-markdown-editor/commit/672695be8b29c57f7fa7ca580d29368b9e57af68

Jetzt haben wir eine schöne, mobilfreundliche, Markdown-basierte Wissensdatenbank mit Videounterstützung, Callouts und Hervorhebung der Codesyntax. Jawohl!

Wir müssen es noch schnell und sicher machen (fast geschafft!).

Wie wir unsere WordPress-Wissensdatenbank superschnell gemacht haben?

Wir haben uns für WP Super Cache entschieden, weil es weit verbreitet ist (über 1 Million aktive Installationen), von Automattic entwickelt und gepflegt wird, kostenlos und relativ einfach einzurichten ist.

Festplattenberechtigungen hinzufügen

Beschreibbaren Caching-Ordner erstellen: mkdir /path/to/your/wordpress/wp-content/cache/ setfacl -Rm user:apache:rwx /path/to/your/wordpress/wp-content/cache Wenn die Berechtigungszeile dies nicht getan hat verwenden Sie Folgendes: chmod 777 /path/to/your/wordpress/wp-content/cache/

Caching aktivieren

Aktiviere das Caching, indem du Folgendes zu deiner wp-config.php Datei hinzufügst:

/** Enable Caching */
define('WP_CACHE', true);
define( 'WPCACHEHOME', '/path/to/your/wordpress/wp-content/plugins/wp-super-cache/' );

Jetzt müssen wir nur noch das Caching einschalten, das geht über WP Admin → Settings → WP Super Cache:Vergessen Sie nicht, zum Speichern auf die Schaltfläche „Status aktualisieren“ zu klicken. Sie können überprüfen, ob das Caching funktioniert, indem Sie eine beliebige Frontend-Seite auf Ihrer WordPress-Site im Inkognito-Modus öffnen und den Quellcode überprüfen. Wenn WP Super Cache funktioniert, sollten Sie den folgenden HTML-Kommentar am Ende des Quellcodes der Seite sehen:

<!-- Dynamic page generated in 0.848 seconds. -->
<!-- Cached page generated by WP-Super-Cache on 2016-10-13 21:35:40 -->

<!-- super cache -->

Das ist schon viel besser, als die Seiten ohne Caching bereitzustellen. Dies löst jedoch immer noch den gesamten Stapel von PHP, WordPress und MySql aus. Wenn wir unsere Seite blitzschnell machen wollen, müssen wir Caching auf Serverebene hinzufügen.

Caching auf Serverebene konfigurieren

Wenn Sie Nginx wie wir verwenden, haben wir hier die Konfiguration verwendet: WP Super Cache Nginx-Konfigurationsregeln TIPP: Die Nginx-Konfigurationsregeln enthalten eine Reihe von if -Regeln. Um Ihnen wertvolle Zeit zu sparen, stellen Sie sicher, dass alle if -Regeln außerhalb der location liegen, da sonst die gesamte Verarbeitung unterbrochen wird (ich habe einige Stunden damit verschwendet, dies herauszufinden). Wenn Sie Apache verwenden, finden Sie die .htaccess mod_rewrite -Regeln direkt auf der Seite mit den Plugin-Installationsanweisungen auf WordPress.org: https://wordpress.org/plugins/wp-super-cache/installation/ Der einfachste Weg, die .htaccess zu testen Caching auf Serverebene ohne Auswirkungen auf Ihre Website erfolgt durch Befolgen dieser Schritte:

Erstellen und veröffentlichen Sie einen Dummy-Post, setzen Sie den folgenden Slug `dummy-cache-test`.
Laden Sie die Seite im Inkognito-Browsermodus und stellen Sie sicher, dass sie zwischengespeichert ist.

Füge den folgenden Code zum oberen Teil deiner wp-config.php Datei hinzu:

if ( false !== strpos($_SERVER[REQUEST_URI], 'dummy-cache-test') {
    echo 'Server caching is off';
    exit;
}

Nachdem Sie den Code hinzugefügt haben, laden Sie die Seite im selben Inkognito-Browsermodus neu. Wenn die Seite korrekt geladen wird – das Caching auf Serverebene ist aktiviert. Wenn Sie die Meldung „Server Caching is off“ erhalten, stimmt etwas nicht.

Vergiss nicht, diesen Zusatz aus der Datei wp-config.php zu entfernen und auch den Dummy-Beitrag zu löschen, wenn du fertig bist. Fantastisch – wir haben das Caching eingestellt, alle Seiten werden jetzt direkt aus den statisch zwischengespeicherten HTML-Dateien bedient, wobei PHP und WordPress übersprungen werden.

CDN hinzufügen

Auch wenn die KB bereits in ziemlich guter Verfassung ist, wird jeder Seitenaufruf von einem neuen Browser unseren Server „treffen“. Daher möchte ich das beseitigen, indem ich eine weitere Schicht hinzufüge – CDN.

Die klaren Vorteile von CDN sind die globale Verteilung von Rechenzentren, hohe Verfügbarkeit und eine massive Verringerung der Serverressourcen, insbesondere wenn die Dinge statisch sind. Seiten werden direkt vom CDN geladen, ohne unsere Server auch nur zu „berühren“.

Ich kann CloudFlare nicht genug loben. Wir verwenden ihr CDN (und ihre Extras) seit Jahren, und was daran verrückt ist – Sie können es kostenlos verwenden! Das ist richtig – absolut kostenlos für 95 % ihrer Funktionen.

Um Ihnen nur ein Beispiel zu geben, nehmen wir an, Sie haben eine beliebte statische Seite auf der Website, die täglich 5 Millionen eindeutige Besuche erhält. Ohne Proxyserver und ISP-Caching würde dies täglich mindestens 5 Millionen Zugriffe auf Ihren Server auslösen. Wenn Sie ein CDN wie CloudFlare verwenden, wird diese statische Seite nur einige Male am Tag von Ihrer Website geladen (basierend auf der CDN-Cache-Bereinigungshäufigkeit).

Hier sind einige echte Statistiken von einer Subdomain, die wir haben und die nur Bilder liefert:

Schauen Sie sich diese Zahlen an – wir haben über 600 GB Bandbreite für unsere Server gespart. Wenn Sie WordPress + WP Super Cache Plugin + Caching auf Serverebene + CloudFlare CDN einrichten, können Sie wahrscheinlich ein DigitalOcean-Droplet für 5 USD / Monat ohne Skalierungsprobleme verwenden!

Lassen Sie uns zusammen etwas rechnen… WordPress ist kostenlos, WP Super Cache ist kostenlos, CloudFlare CDN ist kostenlos… Oh – es kostet nur 5 $/Monat für skalierbares WordPress. Verrückt, oder?!

Wie haben wir die KB-Suche angepasst, um zwischengespeicherte Daten bereitzustellen?

Standardmäßig verwendet die Permalink-Struktur der WordPress-Suche einen s= -Parameter der Abfragezeichenfolge, um die Suchabfrage zu übergeben. Aus gutem Grund ignoriert WP Super Cache Abfragezeichenfolgen. Daher mussten wir einige kleine Änderungen an der Struktur der Such-URLs vornehmen, damit sie funktioniert:

Dieses Update ändert die URL-Struktur in freemius.com/help/documentation/search/{query}/ , die von WP Super Cache zwischengespeichert wird.

Boom! Sogar unsere Suchergebnisse werden jetzt zwischengespeichert.

Wie haben wir unsere WordPress-Wissensdatenbank gesichert?

Sicherheit ist ein Schlüssel. Das Letzte, womit sich ein Unternehmen, insbesondere ein Startup, auseinandersetzen möchte, ist eine Sicherheitsverletzung. Es kann Ihrem Ruf schaden, Ihr IP (Intellectual Property) gefährden und Stunden, manchmal sogar Tage in Anspruch nehmen, um die Kontrolle und die Daten wiederherzustellen.

Viele Entwickler lieben es, Scheiße über WordPress zu reden und zu sagen, dass es unsicher ist. Basierend auf den Zahlen – ja, sie haben wahrscheinlich Recht. Da WordPress die beliebteste Webplattform ist, ist es auch das Ziel Nr. 1 für Hacker, und die Zahlen machen Sinn – duh …

Was sie nicht verstehen, ist, dass WordPress als Plattform wahrscheinlich eines der sichersten Projekte ist. The vulnerabilities are mainly coming from old, outdated WordPress versions, 3rd party plugins and themes, and from users that set up weak passwords.

So the first thing we would like to do is eliminate any notion of WordPress in our source code to reduce the chances of an attack.

1. WordPress adds a bunch of (mostly) unuseful metadata to the head of every page which is pretty much unique to WordPress, let's get rid of that by adding the following code to the theme's functions.php file:

2. Many WordPress plugins add HTML comments with a unique thumbprint that are easily identified. For example, Yoast SEO adds the following code:

<!-- This site is optimized with the Yoast SEO plugin v3.7.0 - https://yoast.com/wordpress/plugins/seo/ -->

That makes it easy for attackers to identify the site as WordPress.

Remember CloudFlare?

It has a checkbox to automatically minify HTML and get rid of all the HTML comments added by different plugins, themes and WordPress core:

Done!

3. Another known identifier of WordPress is the /wp-admin/ path to the login page. We installed WPS Hide Login, and configured our own “secret” path to the login page.

Assuming you set your login to your-site.com/my-secret-login/ make sure you add that path to WP Super Cache exclusion list. You can find it under WP Admin → Settings → WP Super Cache → Advanced:

Otherwise, it might mess up things when using SSL.

4. No need to mention – you and your team should be keeping your passwords strong! You can use a plugin like Force Strong Password to enforce a 'strong passwords' policy.

5. Force your login and WP Admin browsing via HTTPS to prevent password sniffing. You can achieve that by adding the following defines to the wp-config.php file:

define('FORCE_SSL_ADMIN', true);
define('FORCE_SSL_LOGIN', true);

6. One of the most popular attacks on WordPress sites is Brute force attack. Having a strong password policy helps, but can't really protect against it. Thus, we installed Google Captcha plugin that adds a simple captcha validating it's a human being:

Also, we installed Login Watchdog, a lightweight plugin that automatically bans suspicious IPs after pre configured amount of failed logins.

And if you are using CloudFlare as I recommended, it comes with a security layer against any threats, and since it's widely used, it has a “network knowledge” to protect your site from IPs that were attacking other sites powered by CloudFlare.

7. You should also secure WordPress on the server layer, preventing direct access to files like wp-login.php , hiding sensitive files, etc. Just follow this post:
https://lamosty.com/2015/04/14/securing-your-wordpress-site-running-on-nginx/

So yes – as long as there is a login page to our WordPress, it would never be secure as a pure static website. But the fact that we have turned our KB's frontend to static, hidden any evidence that we are using WordPress, added brute force protection and forced the login via HTTPS with a strong password policy, makes it very very (very) hard to hack.

I would dare to say that the only way the Knowledge Base will be hacked is if a security dojo will target our site specifically (that's rare, and I'm NOT calling anyone for a challenge).

Now you

Hopefully, this (very) elaborate article/tutorial will be useful for you when you come to make the important decision of what to go with for your knowledge base documentation solution.
No doubt, there's a lot to take into account here, and many of the decisions we made were influenced by our very specific needs & desires.

You could either copy & paste the entire process and customizations, or go deeper and customize it according to your specific needs. What's more important is to grasp the line of thought that lead the decision making and choosing & picking what's right for us. It was not easy because as I've shown – there are quite a few viable options out there, however, it did pay off, as Freemius now has an awesome Knowledge Base center, which is super customizable, lightning fast and scalable!

Hope you have a clear view how you can get started implementing and setting up your own documentation solution.

Viel Glück!