Jak zbudować przyjazną dla SEO bazę wiedzy pomocy technicznej: Kompletny przewodnik po skalowalnym rozwiązaniu w zakresie dokumentacji

Opublikowany: 2016-10-26

Gdy baza użytkowników Twojego startupu powiększy się, wsparcie stanie się podstawową częścią Twojej firmy. Stworzenie solidnego rozwiązania Bazy Wiedzy jest ważną długoterminową inwestycją, która, miejmy nadzieję, jeśli zostanie zrealizowana prawidłowo, zwróci się, zmniejszając obciążenie wsparcia, zwiększając zasięg SEO witryny i generując nowe leady, które w przeciwnym razie nie zostałyby pozyskane.

Jest to wyczerpujący i techniczny przewodnik dla programistów krok po kroku. Jeśli nie jesteś programistą, prawdopodobnie powinieneś wysłać ten artykuł do swojego CTO. Podziękuje ci za to.

TL; DR: W końcu zbudowaliśmy i wydaliśmy naszą półstatyczną, opartą na przecenach bazę wiedzy dla naszej platformy monetyzacyjnej Freemius, korzystając z WordPressa. Udostępniam tutaj całą książkę kucharską naszych badań; dlaczego wybieramy WordPressa zamiast rozwiązań SaaS i generatorów statycznych; jak to zrobiliśmy (w tym wszystkie dostosowania kodu i konfiguracja na poziomie serwera), czego się nauczyliśmy i jak możesz replikować ten proces, aby zaoszczędzić cenny czas i skonfigurować swój własny, szybki jak błyskawica, skalowalny, zrównoważony, bezpieczny i pół- statyczna KB (Baza Wiedzy) dla własnej wtyczki, motywu lub innego produktu cyfrowego.

Ten 15-minutowy przewodnik pozwoli Ci zaoszczędzić 44 godziny (wykorzystaliśmy śledzenie czasu) badań, dostosowywania, testowania i optymalizacji. Jeśli nadal nie jesteś na etapie tworzenia własnego centrum dokumentacji, po prostu dodaj tę stronę do zakładek i wróć w odpowiednim czasie.

Jesteś gotowy? No to ruszamy.

Motywacja
Czego należy szukać w rozwiązaniu do dokumentacji?
1. Skalowalny i trwały
2. Przyjazne dla użytkownika zaplecze
3. Podtrzymywalny
4. Zoptymalizowany pod kątem SEO
5. Kompatybilny z marką
Wybór odpowiedniej platformy dokumentacji jest trudny!
- Oprogramowanie bazy wiedzy jako usługa
- Statyczne bazy wiedzy
- Bazy wiedzy oparte na WordPress
Dlaczego nie wybraliśmy Help Scout Docs ani żadnej innej bazy wiedzy SaaSy
Dlaczego wybieramy WordPress zamiast statycznych generatorów witryn do naszej bazy wiedzy
Dlaczego wybieramy wtyczkę weDocs WordPress do naszej bazy wiedzy?
Instalowanie i dostosowywanie rozwiązania dokumentacji weDocs
- Dodawanie metadanych Breadcrumbs Rich Snippets
- Dostosowywanie struktury adresu URL bazy wiedzy (permalinki)
- Dodawanie ładnej strony głównej do bazy wiedzy weDocs
- Sprawianie, że weDocs jest przyjazny dla urządzeń mobilnych / responsywny
Używanie Markdown zamiast edycji Rich HTML
- Wybór i instalacja wtyczki Markdown WordPress
- Dodawanie obsługi YouTube i Vimeo Markdown
- Dodawanie obsługi skrótów Nice Callouts
- Dodawanie zakreślacza składni dla Pretty Code
Jak sprawiliśmy, że nasza baza wiedzy WordPress jest super szybka?
- Dodawanie uprawnień do dysku
- Włączanie buforowania
- Konfigurowanie buforowania na poziomie serwera
- Dodawanie CDN
Jak dostosowaliśmy wyszukiwanie KB do obsługi danych w pamięci podręcznej?
Jak zabezpieczyliśmy naszą bazę wiedzy WordPress?
Teraz ty

Motywacja

Dokumentacja była zawsze na naszej liście TODO od pierwszych dni Freemiusa. To powiedziawszy, kiedy produkt jest na wczesnym etapie, nie ma sensu spieszyć się i dokumentować go. Należy skupić się na walidacji założeń i szybkich iteracjach, aż do uzyskania satysfakcjonującego dopasowania produktu do rynku. Uruchomiliśmy Freemiusa około półtora roku temu i w końcu poczuliśmy, że nadszedł czas, aby nadać priorytet dokumentacji.

Czego należy szukać w rozwiązaniu do dokumentacji?

Zanim pospieszyłem z rozwiązaniem, chciałem mieć jakiś plan. Dlatego stworzyłem następującą listę wymagań:

Skalowalny i trwały

Jak każde inne rozwiązanie internetowe, musi być w stanie skalować się wraz z naszym ruchem przy zachowaniu tej samej wydajności. Znalezienie odpowiedzi MUSI też być łatwe, gdy baza wiedzy rozrośnie się ponad tuzin artykułów. Innymi słowy – dobre wyszukiwanie!

Przyjazne dla użytkownika zaplecze

Dodawanie i edytowanie artykułów dokumentacji powinno być łatwe dla każdego członka zespołu, niezależnie od tego, czy jest programistą, czy nie.

Podtrzymywalny

Nic nie trwa wiecznie. Trendy we wzornictwie się zmieniają, a technologia cały czas się rozwija. Powinna więc być stosunkowo łatwa modyfikacja UI Bazy Wiedzy, a w skrajnych przypadkach łatwo eksportować dane i migrować do innego systemu.

Zoptymalizowany pod kątem SEO

Dokumentacja jest treścią. W przeciwieństwie do Twoich postów na blogu, dokumentacja bazy wiedzy koncentruje się wyłącznie na Twoim produkcie. Twoje słowa kluczowe. To świetny sposób na wzmocnienie autorytetu SEO we wszystkim, co sprzedajesz.

Ponadto, gdy użytkownicy czegoś szukają, powszechnym nawykiem jest natychmiastowe skorzystanie z wyszukiwarki. To po prostu łatwiejsze niż otwieranie witryny, szukanie linku Baza wiedzy / Centrum pomocy / Dokumenty, a dopiero potem szukanie rozwiązania. Dlatego lepiej upewnij się, że zawartość Twojej dokumentacji jest widoczna dla wyszukiwarek i jest zoptymalizowana dla nich, zwłaszcza Google, jeśli kierujesz się na rynek anglojęzyczny.

Kompatybilny z marką

Wygląd Bazy Wiedzy powinien pasować do języka projektowania i marki naszej firmy. Obejmuje to kolory, czcionki, styl nagłówka i stopki itp.

Wybór odpowiedniej platformy dokumentacji jest trudny!

Podążając za naturalnym procesem odkrywania, poprosiłem Google o radę. Tym razem Google nie pomogło. Wyniki wyszukiwania były przytłaczające. Nie dość, że na rynku jest tak wiele opcji, to rozwiązania są z natury różne.

Google nie był pomocny. Na rynku jest tak wiele opcji, a rozwiązania są z natury różne.Tweetuj

Oprogramowanie bazy wiedzy jako usługa

Istnieją wyznaczone rozwiązania oprogramowania bazy wiedzy obsługiwane przez firmy pomocy technicznej, takie jak Help Scout Docs i Zendesk Help Center.

Statyczne bazy wiedzy

Statyczne generatory witryn stają się coraz bardziej popularne. Jeśli nie znasz tej koncepcji, ogólna idea jest taka, że większość stron internetowych jest dość statyczna (w tym Twój blog WordPress) i nie ma prawdziwego powodu, aby uruchamiać drenujący stos zaplecza, taki jak WordPress / PHP / MySql. Zamiast tego przenieś ciężki ciężar do silnika przed wdrożeniem, który będzie generował statyczne strony HTML, które można hostować w sieciach CDN, nawet bez dotykania serwerów. Jest oszczędny, skalowalny i bezpieczny.

Istnieją setki generatorów, a silniki takie jak Jekyll i Hugo są bardzo popularne wśród hardcorowej społeczności programistów (nie bez powodu!).

Bazy wiedzy oparte na WordPress

Znalazłem ponad 20 darmowych wtyczek Bazy wiedzy w repozytorium WordPress.org, kolejny tuzin płatnych wtyczek dokumentacji w CodeCanyon i Google oraz kolejny tuzin motywów Centrum pomocy.

Czuć się zmieszanym? Zdecydowanie zrobiłem ¯\(°_o)/¯

Jak widać, zbyt wiele opcji. Postanowiłem wypróbować inną strategię – poprosić o rekomendację osoby, którym ufam opinii. Jestem członkiem grupy na Facebooku o nazwie Sprzedaż produktów WordPress, do której należy wielu moich przyjaciół i wiodących ludzi zajmujących się produktami WordPress. Jestem prawie pewien, że 90% z nich poradziło sobie z tym samym wyzwaniem przede mną, więc zdecydowanie warto było spróbować.

Zanim przesłałem moje pytanie, poszukałem i znalazłem wątek z 2015 roku, założony przez Jean Galea z WP Mayor, który zadaje dokładnie to samo pytanie:

Świetny! pomyślałem sobie. A potem zacząłem czytać odpowiedzi…

Adrian Labos korzysta z Zendesk Help Desk
Pippin Williamson (Pippin Plugins) i Adam Pickering (Astoundify) używają Help Scout Docs
Phil Derksen używa WordPressa z motywem KnowHow
Dejan Markovic (Hype Social) używa WordPressa z wtyczką weDocs
Devin Walker (WordImpress) używa WordPressa z CPT i wtyczką ACF.
Ahmad Awais, który zbudował motyw DocPress, mówi, że „utrzymywanie witryny z dokumentami za pomocą WordPressa stało się nieefektywne, gdy liczba produktów rośnie”, a teraz buduje statyczną bazę wiedzy za pomocą silnika szablonów Jade.
Tom Hemsley (wtyczka Mega Menu) polecił korzystanie z WordPressa z wtyczką Heroic Knowledge Base.
Pojawiły się kolejne trzy odpowiedzi na temat dodatkowych wtyczek WordPress od ich autorów, które są częścią grupy.

Jak widać, po prostu nie ma konsensusu. Niestety nie było to zbyt pomocne.

Cholera – czas na rozeznanie…

WSKAZÓWKA: Na marginesie, jeśli jesteś osobą produktową w sferze WordPress, gorąco polecam aplikowanie do tej grupy.

Zapisz się i zdobądź bezpłatną kopię naszego

Książka biznesowa wtyczki WordPress

Dokładnie jak stworzyć dobrze prosperujący biznes wtyczek WordPress w gospodarce subskrypcyjnej.

Dziękuję za zasubskrybowanie!

- właśnie wysłaliśmy Twoją kopię „The WordPress Plugin Business Book” do .

Masz literówkę w swoim e-mailu? kliknij tutaj, aby edytować adres e-mail i wyślij ponownie.

Dlaczego nie wybraliśmy Help Scout Docs ani żadnej innej bazy wiedzy SaaSy

Jestem fanem Help Scout i używamy ich w naszym systemie zgłoszeń do pomocy technicznej. Właściwie przyjaźnię się z założycielami. W 2011 roku pracowaliśmy przy biurku 2 i spędzaliśmy razem 4 miesiące, uczestnicząc w programie akceleracyjnym Techstars w Bostonie. To było wtedy, gdy Help Scout to tylko Denny, Jared i Nick.

Dokumenty to całkiem solidne rozwiązanie do tworzenia dokumentacji i prawdopodobnie najłatwiejszy i najszybszy sposób. Jest również zaskakująco konfigurowalny. Ale podobnie jak inne platformy SaaS, ma wady SEO.

1. Utworzenie bazy wiedzy lub jakiejkolwiek innej zawartości w podkatalogu jest nadal znacznie lepsze niż w subdomenie pod względem rankingu wyszukiwania. Rand Fishkin, założyciel MOZ (wiodącej na świecie firmy SEO) ma świetny film z 2015 roku z prawdziwymi przypadkami użycia omawiającymi ten temat.

Niestety, ze względu na sposób działania plików stref DNS nie ma możliwości skonfigurowania rekordu CNAME w podkatalogu.

Aby upewnić się, że nie przegapiłem żadnego obejścia, skontaktowałem się z zespołem pomocy technicznej Help Scout i oto odpowiedź, którą otrzymałem:

„Nienawidzę przynosić złych wieści, ale nie ma sposobu na umieszczenie Dokumentów w podkatalogu. Mamy interfejs API dla Dokumentów, który pozwala wyeksportować witrynę i samodzielnie ją hostować, ale konieczne byłoby przebudowanie części wyglądu i funkcji: http://developer.helpscout.net/docs-api/
Obawiam się, że byłoby to jedyne rozwiązanie, jeśli nadal chcesz używać Dokumentów i mieć je jako podkatalog.

2. Nie sprawdziłem innych rozwiązań z poprzedniego powodu, ale w szczególności Help Scout Docs nie zawiera metadanych Rich-Snippets dla bułki tartej i wyszukiwania.

Tak wygląda wynik z Help Scout Docs w SERP Google (strona wyników wyszukiwania):

Oto wynik strony, która zawiera metadane fragmentów rozszerzonych w bułce tartej:

A oto wynik strony, która zawiera metadane opisów rozszerzonych wyszukiwania:

Nie będę zagłębiać się w ten temat, ale ogólnie metadane opisów rozszerzonych pomagają wyszukiwarce lepiej zrozumieć zawartość witryny i jej strukturę. Wiodące na świecie wyszukiwarki: Google, Yahoo i Bing; może przełożyć te dane na wizualizacje, które zwiększają CTR w sieci wyszukiwania (współczynnik klikalności). Podsumowując – uzyskasz większy ruch.

Skontaktowałem się również z Chrisem Mooney, współzałożycielem HeroThemes, firmy, która koncentruje się solo na rozwiązaniach z bazy wiedzy, i potwierdził, że SEO jest jednym z głównych powodów, dla których klienci migrują do swojego rozwiązania dokumentacji on-prem.

Aby podkreślić znaczenie SEO, jakie można uzyskać z dobrze napisanej dokumentacji, chciałbym podzielić się krótką historią. W 2011 roku spotkałem się z Elad Eran, wiceprezesem ds. rozwiązań dla klientów w WiX. Eran z dumą wyjaśnił, że ich oprogramowanie bazy wiedzy i fora pomocy technicznej są jednym z głównych katalizatorów, które pomogły WiX osiągnąć wysoką pozycję w Google i uzyskać bezpłatny, wysokiej jakości ruch organiczny.

Fora dotyczące oprogramowania i pomocy technicznej Bazy wiedzy są jednym z głównych katalizatorów, które pomogły WiX uzyskać wysoką pozycję w Google i uzyskać bezpłatny, wysokiej jakości ruch organiczny.Tweetuj

Jeśli to jest dobre dla WiX, powinno być dobre dla nas

Dlaczego wybieramy WordPress zamiast statycznych generatorów witryn do naszej bazy wiedzy

Główne zalety statyki z silnikiem takim jak Jekyll to szybkość, skalowalność i bezpieczeństwo.

Czy możemy je zdobyć z WordPressem? Odpowiedź brzmi – prawie.

Ponieważ strony dokumentacji są statyczne (z wyjątkiem wyszukiwania), możemy łatwo zainstalować jedną z kilkudziesięciu darmowych wtyczek buforujących WordPress, skonfigurować Nginx tak, aby obsługiwał pliki z pamięci podręcznej bezpośrednio z dysku, pomijając silnik WordPressa, a także skorzystać z darmowej usługi CDN, takiej jak CloudFlare do dystrybucji naszych plików w różnych centrach danych na całym świecie. Może to brzmieć skomplikowanie, ale tak naprawdę nie jest i wkrótce wszystko wyjaśnię.

To sprawi, że nasz interfejs dokumentacji stanie się całkowicie statyczny. Będzie się świetnie skalować i będzie superszybki (ponieważ jest statyczny). W00t! W00t!

Jeśli chodzi o bezpieczeństwo, cóż, nic nie jest idealne. Ale możemy podjąć pewne podstawowe środki ostrożności, używając kilku darmowych wtyczek i konfiguracji na poziomie serwera, które zmniejszą szansę ataku o 99,9%. Omówię to wyraźnie za chwilę, włączając wszystkie składniki.

Z drugiej strony wady statycznego podejścia naszego zespołu to:

Jako zespół będziemy musieli zdobyć nowy zestaw umiejętności technicznych, skonfigurować dodatkowe środowisko programistyczne i prowadzić ciągły proces wdrażania, aby upewnić się, że dodawanie lub edytowanie plików nie wymaga interwencji programisty. Jest to zdecydowanie wykonalne, ale wymaga czasu.
Wyszukiwanie jest (w większości) funkcją dynamiczną, więc jeśli przejdziemy w tryb statyczny, będziemy musieli zaimplementować interfejs API RESTful lub zintegrować usługę wyszukiwania innej firmy, taką jak Algolia. Kolejny ból głowy do pokonania.
Kontrola wersji nie jest systemem CMS. Chociaż uwielbiam GitHub i BitBucket, mogą być przerażające dla osób, które nie znają się na technologii. Mimo że wszyscy członkowie naszego zespołu są programistami z przeszłości, prawdopodobnie zmieni się to w przyszłości.

WSKAZÓWKA: Warto wspomnieć, że podczas moich badań znalazłem fajny projekt o nazwie Prose.io, który umożliwia prostą edycję treści WYSIWYG plików GitHub i BitBucket.

Podsumowując, możemy czerpać większość korzyści ze statycznych witryn bez utraty elastyczności WordPressa, zachowując przyjazny dla użytkownika edytor CMS i uzyskując edycję w czasie rzeczywistym bez ciągłego procesu wdrażania.

Dlaczego wybieramy wtyczkę weDocs WordPress do naszej bazy wiedzy?

Jak wspomniałem wcześniej, widziałem co najmniej 30 wtyczek i motywów WordPress dla Baz wiedzy.

Ponieważ prowadzimy startup, ocena ich wszystkich nie jest możliwa. Spróbujmy więc iść z eliminacją.

Motywy Bazy wiedzy są już dostępne!

Zdecydowaliśmy się nie korzystać z żadnych motywów dokumentacji, ponieważ większość z nich używa domyślnej taksonomii obiektu post i category dla artykułów z dokumentacją. To rozwiązanie może działać, jeśli skonfigurujesz dedykowaną instancję WordPress tylko dla Twojej aplikacji z bazy wiedzy. Jeśli chcesz mieć całą swoją witrynę na tej samej instalacji WordPressa, w tym bloga, wszystko może i prawdopodobnie będzie bałaganiarskie ze względu na mieszankę typów treści.

Tak – mamy teraz tylko 20 wtyczek do przetestowania…

Przetestowałem cztery różne darmowe wtyczki:

Baza wiedzy CPT
Baza wiedzy WP
Pomoc WP
weDocs

Dość szybko odkryłem, że wszyscy wykorzystują WordPress CPT (Custom Post Types) i niestandardową taksonomię dla tagów i kategorii. Główna i jedyna istotna różnica dotyczy hierarchii struktury danych.

Baza wiedzy CPT i WP Knowledge Base są płaskie. Podobnie jak w przypadku postów na blogu, istnieją kategorie, tagi i artykuły. Nie ma możliwości powiązania artykułu z artykułem nadrzędnym.

Tak więc struktura bazy wiedzy z tymi wtyczkami będzie składać się z kategorii jako sekcji i postów jako dokumentów.

 Kategoria 1
↳Dokument 1
↳Dokument 2

Kategoria 2
↳Dokument 3
↳Dokument 4

Zaletą tej struktury jest to, że możesz powiązać dokument z wieloma kategoriami i wyświetlać go w wielu sekcjach.

 Kategoria 1
↳Dokument 1
...
Kategoria 2
↳Dokument 3
↳Dokument 1

Z drugiej strony struktura artykułów WP Help i weDocs jest podobna do stron. Każdy dokument może być powiązany z dowolnym innym dokumentem jako nadrzędny. Ale może być powiązany tylko z jednym rodzicem (nie jak z kategorią).

 Dokument 1
↳Dokument 2
↳Dokument 3
↳Dokument 4
↳Dokument 5
↳Dokument 6

Taka konstrukcja ma dwie zalety:

Jest bardziej uporządkowany. To zmusza do zastanowienia się, gdzie dokładnie jest najbardziej odpowiednie miejsce do dodania artykułu z dokumentacją.
Kategorie nie mają określonego „porządku”. Dlatego nie ma gotowego sposobu na uporządkowanie kategorii w sposób, w jaki jest to możliwe w przypadku postów, które mają właściwość menu_order .

Powyższe powody były dokładnie tym, dlaczego zdecydowaliśmy się na wtyczki hierarchiczne.

Świetnie – teraz znam rodzaj struktury danych, jakiej potrzebujemy do naszej dokumentacji.

Następnie spędziłem czas na czytaniu o dwóch wtyczkach premium – wpDocs (wersja pro WP Knowledge Base) i Heroic Knowledge Base. Oba wyglądają imponująco wizualnie, ale…

Nie mogłem znaleźć żadnej znaczącej różnicy między tymi dwiema wtyczkami premium a darmowymi wtyczkami.
Obie wtyczki wykorzystują płaską strukturę danych, z której zdecydowaliśmy się nie korzystać.

A więc tak – prawdopodobnie było jeszcze 10 wtyczek, na które nawet nie spojrzałem, ale schemat był jasny.

Zdecydowaliśmy się przejść z weDocs przez WP Help z kilku powodów:

Interfejs użytkownika przeciągnij i upuść w ustawieniach administratora weDocs jest nowoczesny, przyjazny dla użytkownika i atrakcyjny wizualnie.
WP Help nie zawiera niestandardowej taksonomii dokumentów. Co oznacza, że kategorie i tagi nie są dostarczane po wyjęciu z pudełka.
WP Help w ogóle nie obsługuje bułki tartej.
WeDocs jest dostarczany z zestawem niestandardowych szablonów, które sprawią, że dokumentacja będzie wyglądać dobrze od razu (oczywiście wymagało to pewnego dostosowania interfejsu użytkownika).
weDocs ma ciągły przepływ interfejsu użytkownika. Na końcu każdego artykułu możesz przejść do następnego w kolejce.

Przejdźmy do części zabawnej – implementacji…

Instalowanie i dostosowywanie rozwiązania dokumentacji weDocs

Aby rozpocząć, pobierz i zainstaluj weDocs bezpośrednio z repozytorium WordPress.org:
https://wordpress.org/plugins/wedocs/

Teraz nadszedł czas na kilka dostosowań:

Dodawanie metadanych Breadcrumbs Rich Snippets

Ponieważ nie chcieliśmy zmieniać rzeczywistej wtyczki (jeśli to możliwe), użyliśmy szablonu weDocs i pliku functions.php motywu, aby zastąpić domyślne renderowanie bułki tartej.

Skopiuj /wedocs/templates/single-docs.php do /your-theme/wedocs/single-docs.php .
Dodaj następujący kod do pliku functions.php motywu:
Otwórz /your-theme/wedocs/single-docs.php i zastąp wywołanie wedocs_breadcrumbs() freemius_wedocs_breadcrumbs() .
Ponieważ zmodyfikowaliśmy również strukturę HTML bułki tartej do nieuporządkowanej listy ( <ul> ) dla lepszej semantyki, dodaj następujący kod SASS do swojego motywu:

Aby uzupełnić fragmenty rozszerzone, musisz dodać następujący kod do tagu <body> :

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

Dostosowywanie struktury adresu URL bazy wiedzy (permalinki)

weDocs jest dostarczany z następującą domyślną strukturą permalinków:
your-site.com/wordpress-root/docs/

Chcieliśmy mieć naszą dokumentację na freemius.com/help/documentation/, która powinna mieć lepszą pozycję w SEO podczas wyszukiwania dokumentacji. Chcieliśmy również zachować stronę „pomoc”, aby w przyszłości dodać Centrum pomocy, abyśmy mogli używać struktur adresów URL, takich jak /help/faq/ dla strony z najczęściej zadawanymi pytaniami i /help/forum/ dla forum.

Moglibyśmy to łatwo osiągnąć, modyfikując reguły przepisywania docs CPT w kodzie wtyczki. Ale ponieważ chcemy uniknąć zmiany kodu wtyczki, wymyśliliśmy sposób, aby zrobić to pośrednio w pliku functions.php motywu:
Dodatkowo dodaliśmy obsługę fragmentów artykułów (potrzebujemy ich do następnej personalizacji), autora dokumentów, pól niestandardowych i atrybutów strony. Ważne: weDocs jest domyślnie ustrukturyzowany dla Bazy wiedzy obejmującej wiele produktów. Tak więc, jeśli chcesz mieć strukturę /help/documentation/ , upewnij się, że dokument najwyższego poziomu, który tworzysz w back office, nazywa się Documentation (slug musi być documentation ).

Dodawanie ładnej strony głównej do bazy wiedzy weDocs

Domyślnie weDocs jest dostarczany z krótkim kodem, który może pomóc w stworzeniu strony domowej, która będzie wyglądać tak:

Nie jest źle, ale osobiście wolę układ generowany przez Help Scout Docs :

Zawiera krótki opis każdej sekcji i wygląda dla mnie bardziej atrakcyjnie wizualnie. Najpierw utwórzmy szablony PHP, dodając docs-header-main.php i docs-sections.php do folderu /your-theme/wedocs/ . Kod można znaleźć w następującym skrócie: https://gist.github.com/vovafeldman/adbf1c071a08b7565df11d709b2f1240 Jeśli zagłębisz się w kod pliku docs-header-main.php , zauważysz, że również wkradłem się w bogate wyszukiwanie metadane fragmentów. Teraz, ponieważ artykuł /help/documentation/ jest po prostu kolejnym artykułem w Bazie wiedzy, domyślnym szablonem używanym przez WordPress jest /wedocs/single-docs.php . Dlatego musimy dodać następujący fragment kodu na początku tego pliku, aby załadować nowe szablony sekcji, gdy rodzic artykułu nie jest ustawiony:

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

  return;
}

Sprawianie, że weDocs jest przyjazny dla urządzeń mobilnych / responsywny

Niestety, weDocs nie jest dostarczany z responsywnymi regułami CSS. Oto jak to wygląda w Bazie wiedzy weDevs (twórców weDocs):

Nie będę zagłębiać się w CSS, ale ogólnie dodaliśmy zapytania o media, które:

Ukryj bułkę tartą.
Spraw, aby zawartość była pełna szerokość z ładnym wypełnieniem.
Przeniesiono pasek boczny nawigacji i wyszukiwanie na dół, tuż przed stopką.

Oto wynik:

A tak wygląda strona sekcji:

Świetnie! Skończyliśmy z dostosowywaniem weDocs.

Używanie Markdown zamiast edycji Rich HTML

Jednym z początkowych wymagań KB był zrównoważony rozwój – możliwość łatwej zmiany projektu i potencjalnie platformy (pamiętacie?). Korzystanie z edycji treści HTML Rich to miecz obosieczny. Z jednej strony jest niezwykle elastyczny i daje swobodę dostosowywania stylu treści według własnego uznania. Z drugiej strony ten brak struktury pozwala każdemu autorowi treści robić, co chce. Nie jest to trwałe, co jeszcze bardziej komplikuje zmiany w projekcie i utrudnia migrację. Na przykład użycie <strong> vs. <b> . Lub używając tabel opartych na <table> i <div> . Są to decyzje związane ze składnią, a każda osoba ma swój niepowtarzalny styl pisania.

To, na czym autorzy treści powinni się skupić, to treść i semantyka, a nie projektowanie.

Istnieje wiele języków znaczników ze składnią formatowania zwykłego tekstu, chociaż Markdown był naturalnym wyborem, ponieważ jest powszechnie używany przez gigantów, takich jak GitHub, Atlassian i sam WordPress.

Wybór i instalacja wtyczki Markdown WordPress

W repozytorium WordPress.org są tylko dwie wtyczki Markdown, które mają ponad 1000 aktywnych instalacji. WP-Markdown i JP Markdown. Tak, Jetpack ma również moduł Markdown, ale instalowanie tego „potwora” tylko dla jednego modułu nie miało sensu. Początkowo zainstalowałem WP-Markdown, ponieważ na podstawie zrzutów ekranu miał możliwość łatwego wyboru typów postów, które będą obsługiwać przeceny. Niestety wtyczka nie działała (ostatnia aktualizacja miała miejsce ponad 3 lata temu), więc ostatecznie jej nie używaliśmy. Następnie zainstalowałem JP Markdown. Wtyczka działała, ale miała kilka rzeczy, które mi się nie podobały:

Przecena została automatycznie aktywowana na wszystkich postach i stronach.
Składnia markdown nie została zachowana, została automatycznie przekonwertowana na stylizowany kod HTML:

To jest złe, ponieważ dane są przechowywane w bazie danych jako bogaty HTML, a nie jako przecena (sprawdziłem to). Ponadto nie dodaje żadnych ograniczeń dotyczących edycji sformatowanego kodu HTML. Jeśli więc w przyszłości chcielibyśmy przeprowadzić migrację do innego systemu, nie ma możliwości wyeksportowania przecen.

Potem znalazłem edytor WP Markdown, który używa modułu Markdown z Jetpack i to był ten, którego ostatecznie używaliśmy. Mimo że wciąż musieliśmy dokonać kilku dostosowań:

Wtyczka wyłącza rozbudowaną edycję wszystkich postów i stron po aktywacji. Chcieliśmy pozbyć się bogatej edycji tylko na naszych stronach dokumentacji.
Wtyczka zastępuje istniejący edytor własnym edytorem przecen dla wszystkich postów i stron. Ponownie, chcieliśmy mieć to tylko na naszych stronach z dokumentacją.

Możesz zobaczyć te zmiany tutaj:
https://github.com/Freemius/wp-markdown-editor/commit/706bce0c23943c82d102c67a09e18dac32c66207

Wersję rozwidloną możesz pobrać stąd (tylko kilka drobnych zmian):
https://github.com/Freemius/wp-markdown-editor

Następnie dodaliśmy krótką funkcję, która rejestruje docs CPT w celu obsługi edycji znaczników oraz wyrejestrowuje typy post i page , aby zachować bogaty edytor HTML:

Na koniec musieliśmy dostosować domyślną funkcję eksportowania WordPressa, aby eksportował kod przeceny, a nie zawartość bogatą w HTML. Zrobiliśmy to, podłączając się do the_content_export :
Niesamowite – nasza baza wiedzy jest oparta na przecenach i można ją łatwo wyeksportować.

Dodawanie obsługi YouTube i Vimeo Markdown

Filmy są istotną częścią każdej Bazy Wiedzy. Niestety, Markdown nie obsługuje filmów. Na szczęście WordPress sprawia, że dodawanie shortcode jest bardzo łatwe i za pomocą kilku linijek kodu. Wzbogaciliśmy naszą składnię Markdown, aby wspierać dodawanie filmów z YouTube i Vimeo:

Jako bonus sprawiliśmy, że rozmiar wideo jest responsywny i przyjazny dla urządzeń mobilnych, a dodawanie filmów jest teraz intuicyjne i proste dzięki identyfikatorowi wideo:
[youtube gj6aoYG4fUI]
[vimeo 185625717]

Dodawanie obsługi skrótów Nice Callouts

Domyślna składnia Markdown obsługuje cytaty blokowe, ale nie zawiera semantyki dla różnych objaśnień, takich jak wskazówki i ostrzeżenia, które nie są obowiązkowe, ale ważne dla dobrej bazy wiedzy.

Skróty WordPress ponownie na ratunek

A oto jak to wygląda na frontendzie:

Dodaliśmy prefiks fs_ , aby zapobiec potencjalnym konfliktom z wtyczkami, które możemy zainstalować w przyszłości.

Dodawanie zakreślacza składni dla Pretty Code

Ani WordPress, ani WP Markdown Editor nie zawierają podświetlania składni kodu. Ponieważ Freemius jest platformą dla programistów, a nasza dokumentacja zawiera przykłady kodu, dodanie podświetlania składni było kluczowe. Zdecydowaliśmy się na SyntaxHighlighter Evolved, ponieważ jest on obsługiwany przez Automattic, podobnie jak podstawowy moduł Markdown Jetpack, który jest używany przez wtyczkę WP Markdown Editor. Spojrzenie na kod renderowania przecen ujawnia, że faktycznie zintegrowały się ze sobą:

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

Świetny! Prawidłowy? Niestety wygląda na to, że nic nie jest idealne po wyjęciu z pudełka, a kod był renderowany nieprawidłowo. Zepsuł sekcje wielowierszowego kodu Markdowna, zmieniając znaki specjalne do odpowiadających im jednostek HTML. Nie dość, że „łamał” wyrenderowany kod na interfejsie, to także przechowywał w bazie danych wersję HTML części kodu Markdowna. A to źle wpływa na zachowanie treści i potencjalny eksport danych. W związku z tym nie mieliśmy innego wyjścia, jak tylko wprowadzić kilka poprawek w kodzie wtyczki. Dokładne zmiany możesz zobaczyć tutaj:
https://github.com/Freemius/wp-markdown-editor/commit/672695be8b29c57f7fa7ca580d29368b9e57af68

Teraz mamy piękną, przyjazną dla urządzeń mobilnych bazę wiedzy opartą na Markdown, z obsługą wideo, objaśnieniami i podświetlaniem składni kodu. TAk!

Nadal musimy to zrobić szybko i bezpiecznie (prawie na miejscu!).

Jak sprawiliśmy, że nasza baza wiedzy WordPress jest super szybka?

Wybraliśmy WP Super Cache, ponieważ jest bardzo popularny (ponad 1 mln aktywnych instalacji), opracowany i utrzymywany przez Automattic, bezpłatny i stosunkowo łatwy w konfiguracji.

Dodawanie uprawnień do dysku

Utwórz zapisywalny folder pamięci podręcznej: mkdir /path/to/your/wordpress/wp-content/cache/ setfacl -Rm user:apache:rwx /path/to/your/wordpress/wp-content/cache Jeśli wiersz uprawnień nie pracy, użyj następującego: chmod 777 /path/to/your/wordpress/wp-content/cache/

Włączanie buforowania

Włącz buforowanie, dodając następujące elementy do pliku wp-config.php :

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

Teraz wystarczy włączyć buforowanie, możesz to zrobić przez WP Admin → Ustawienia → WP Super Cache: Nie zapomnij kliknąć przycisku „Aktualizuj status”, aby zapisać. Możesz sprawdzić, czy buforowanie działa, otwierając dowolną stronę frontendową w witrynie WordPress w trybie incognito i sprawdzając kod źródłowy. Gdy WP Super Cache działa, powinieneś zobaczyć następujący komentarz HTML na dole kodu źródłowego strony:

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

<!-- super cache -->

To już o wiele lepsze niż serwowanie stron bez buforowania. Ale to nadal uruchamia cały stos PHP, WordPress i MySql. Jeśli chcemy, aby nasza strona działała błyskawicznie, musimy dodać buforowanie na poziomie serwera.

Konfigurowanie buforowania na poziomie serwera

Jeśli używasz Nginx, tak jak my, oto konfiguracja, której użyliśmy: Reguły konfiguracji WP Super Cache Nginx WSKAZÓWKA: Reguły konfiguracji Nginx zawierają kilka reguł if . Aby zaoszczędzić cenny czas, upewnij się, if wszystkie reguły wykraczają poza dyrektywę dotyczącą location , w przeciwnym razie spowoduje to przerwanie całego przetwarzania (zmarnowałem kilka godzin na zastanawianie się). Jeśli używasz Apache, możesz znaleźć reguły .htaccess mod_rewrite bezpośrednio na stronie instrukcji instalacji wtyczki na WordPress.org: https://wordpress.org/plugins/wp-super-cache/installation/ Najprostszy sposób na przetestowanie buforowanie na poziomie serwera bez wpływu na Twoją witrynę polega na wykonaniu następujących kroków:

Utwórz i opublikuj fikcyjny post, ustaw następujący slug `dummy-cache-test`.
Załaduj stronę w trybie incognito przeglądarki, upewniając się, że jest zapisana w pamięci podręcznej.

Dodaj następujący kod do górnej części pliku wp-config.php :

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

Po dodaniu kodu odśwież stronę w tym samym trybie przeglądarki incognito. Jeśli strona jest załadowana poprawnie – buforowanie na poziomie serwera jest WŁĄCZONE Jeśli pojawi się komunikat „Buforowanie serwera jest wyłączone”, oznacza to, że coś jest nie tak.

Nie zapomnij usunąć tego dodatku z pliku wp-config.php , a także usuń fikcyjny post, gdy skończysz. Fantastycznie – ustawiliśmy buforowanie, wszystkie strony są teraz obsługiwane bezpośrednio ze statycznych zbuforowanych plików HTML, pomijając PHP i WordPress.

Dodawanie CDN

Mimo że KB jest już w całkiem niezłym stanie, każde wyświetlenie strony z nowej przeglądarki „uderzy” w nasz serwer. Dlatego chcę to wyeliminować dodając jeszcze jedną warstwę – CDN.

Oczywiste korzyści z CDN to globalna dystrybucja centrów danych, wysoka dostępność i ogromny spadek zasobów serwera, zwłaszcza gdy sytuacja jest statyczna. Strony będą ładowane bezpośrednio z CDN, nawet bez „dotykania” naszych serwerów.

Nie mogę mówić wystarczająco dobrze o CloudFlare. Korzystamy z ich CDN (i ich dodatkowych gadżetów) od lat i co jest w tym wszystkim szalonego – możesz z niego korzystać za darmo! Zgadza się – całkowicie za darmo dla 95% ich funkcji.

Aby dać ci przykład, załóżmy, że masz popularną statyczną stronę w witrynie, która ma 5 milionów unikalnych odwiedzin dziennie. Ignorując serwery proxy i buforowanie ISP, spowodowałoby to co najmniej 5 mln codziennych trafień na Twój serwer. Kiedy używasz CDN, takiego jak CloudFlare, ta statyczna strona będzie ładowana z Twojej witryny tylko kilka razy dziennie (w oparciu o częstotliwość czyszczenia pamięci podręcznej CDN).

Oto kilka prawdziwych statystyk z subdomeny, którą mamy, która obsługuje tylko obrazy:

Spójrz na te liczby – zaoszczędziliśmy ponad 600 GB przepustowości dla naszych serwerów. Jeśli skonfigurujesz WordPress + WP Super Cache Plugin + buforowanie na poziomie serwera + CloudFlare CDN, prawdopodobnie możesz użyć kropli DigitalOcean o wartości 5 USD / mc bez żadnych problemów ze skalowaniem!

Zróbmy razem trochę matematyki… WordPress za darmo, WP Super Cache za darmo, CloudFlare CDN za darmo… Och – to tylko 5 USD miesięcznie za skalowalnego WordPressa. Szalony, prawda?!

Jak dostosowaliśmy wyszukiwanie KB do obsługi danych w pamięci podręcznej?

Domyślnie struktura permalinków wyszukiwania WordPress używa parametru ciągu zapytania s= do przekazania zapytania wyszukiwania. Nie bez powodu WP Super Cache ignoruje ciągi zapytań. Dlatego musieliśmy wprowadzić kilka drobnych poprawek w strukturze adresów URL wyszukiwania, aby działała:

Ta aktualizacja zmienia strukturę adresów URL na freemius.com/help/documentation/search/{query}/ , która jest buforowana przez WP Super Cache.

Bum! Nawet nasze wyniki wyszukiwania są teraz buforowane.

Jak zabezpieczyliśmy naszą bazę wiedzy WordPress?

Bezpieczeństwo to klucz. Ostatnią rzeczą, z którą każda firma, a zwłaszcza startup, chce się zajmować, jest naruszenie bezpieczeństwa. Może to zaszkodzić Twojej reputacji, zagrozić Twojemu IP (własności intelektualnej) i zabrać godziny, a czasem nawet dni, na odzyskanie kontroli i danych.

Wielu programistów uwielbia gadać gówno o WordPressie i twierdzi, że jest niepewny. Na podstawie liczb – tak, prawdopodobnie mają rację. Ponieważ WordPress jest najpopularniejszą platformą internetową, jest również celem nr 1 dla hakerów, a liczby mają sens – Duh…

Nie rozumieją, że WordPress jako platforma jest prawdopodobnie jednym z najbezpieczniejszych projektów. 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:

Gotowy!

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.

Good luck!