Como construir uma base de conhecimento de suporte amigável para SEO: o guia completo para uma solução de documentação escalável

Publicados: 2016-10-26

Uma vez que a base de usuários da sua startup cresce, o suporte se torna uma parte fundamental do seu negócio. Configurar uma solução sólida de base de conhecimento é um importante investimento de longo prazo, que esperamos que, se feito corretamente, seja recompensado reduzindo a carga de suporte, ampliando o alcance de SEO do seu site e gerando novos leads que, de outra forma, não teriam sido alcançados.

Este é um guia passo a passo abrangente e técnico para desenvolvedores. Se você não é um desenvolvedor, provavelmente deve enviar este artigo ao seu CTO. Ele/ela vai agradecer por isso.

TL;DR: Finalmente construímos e lançamos nossa Base de Conhecimento semi-estática e baseada em markdown para nossa plataforma de monetização Freemius, usando WordPress. Estou compartilhando o livro de receitas completo de nossa pesquisa aqui; por que escolhemos WordPress em vez de soluções SaaS e geradores estáticos; como fizemos isso (incluindo todas as personalizações de código e configuração em nível de servidor), o que aprendemos e como você pode replicar esse processo para economizar tempo valioso e configurar seu próprio KB estático (Base de Conhecimento) para seu próprio plugin, tema ou qualquer outro produto digital.

Este guia de 15 minutos economizará 44 horas (usamos o rastreamento de tempo) de pesquisa, personalização, teste e otimização. Se você ainda não está no estágio de configurar seu próprio centro de documentação, basta marcar esta página e voltar quando for a hora certa.

Você está pronto? Aqui vamos nós.

Motivação
O que você deve procurar em uma solução de documentação?
1. Escalável e durável
2. Back Office amigável
3. Sustentável
4. Otimizado para SEO
5. Compatível com a marca
Escolher a plataforma de documentação certa é difícil!
- Software de base de conhecimento como serviço
- Bases de conhecimento estáticas
- Bases de conhecimento baseadas em WordPress
Por que não escolhemos Help Scout Docs ou qualquer outra base de conhecimento SaaSy
Por que escolhemos o WordPress em vez de geradores de sites estáticos para nossa base de conhecimento
Por que escolhemos o plugin weDocs WordPress para nossa base de conhecimento?
Instalando e Personalizando a Solução de Documentação do weDocs
- Adicionando Metadados de Rich-Snippets de Breadcrumbs
- Personalizando a estrutura de URL da base de conhecimento (links permanentes)
- Adicionando uma página inicial bonita à base de conhecimento do weDocs
- Tornando o weDocs compatível com dispositivos móveis / responsivo
Usando Markdown em vez de HTML Rich Editing
- Escolhendo e instalando um plugin WordPress Markdown
- Adicionando suporte ao YouTube e Vimeo Markdown
- Adicionando suporte a códigos de acesso de chamadas agradáveis
- Adicionando SyntaxHighlighter para Pretty Code
Como tornamos nossa base de conhecimento do WordPress super rápida?
- Adicionando permissões de disco
- Ativando o cache
- Configurando o cache no nível do servidor
- Adicionando CDN
Como personalizamos a pesquisa da base de conhecimento para fornecer dados em cache?
Como protegemos nossa base de conhecimento do WordPress?
Agora você

Motivação

A documentação sempre esteve em nossa lista de TODOs desde os primeiros dias do Freemius. Dito isto, quando o produto está em estágio inicial, não faz sentido apressar e documentá-lo. O foco deve ser validar suposições e iterações rápidas, até chegar a um ajuste satisfatório do produto ao mercado. Iniciamos o Freemius há cerca de um ano e meio e finalmente sentimos que era hora de priorizar a documentação.

O que você deve procurar em uma solução de documentação?

Antes de correr para uma solução, eu queria ter algum tipo de plano. Portanto, criei a seguinte lista de requisitos:

Escalável e durável

Como qualquer outra solução baseada na web, ela deve ser capaz de escalar com nosso tráfego, mantendo o mesmo desempenho. Também DEVE continuar sendo fácil encontrar respostas quando a base de conhecimento crescer além de uma dúzia de artigos. Em outras palavras – boa pesquisa!

Back Office amigável

Adicionar e editar artigos de documentação deve ser fácil para qualquer membro da equipe, sejam eles desenvolvedores ou não.

Sustentável

Nada dura para sempre. As tendências de design estão mudando e a tecnologia está evoluindo o tempo todo. Portanto, deve ser relativamente fácil modificar a interface do usuário da Base de Conhecimento e, em casos extremos, exportar facilmente os dados e migrar para um sistema diferente.

Otimizado para SEO

Documentação é conteúdo. Ao contrário das postagens do seu blog, a documentação da Base de conhecimento é focada exclusivamente no seu produto. Suas palavras-chave. É uma ótima maneira de fortalecer sua autoridade de SEO em tudo o que você está vendendo.

Além disso, quando os usuários pesquisam algo, o hábito comum é usar um mecanismo de busca imediatamente. É mais fácil do que abrir seu site, procurar o link Base de Conhecimento/Central de Ajuda/Documentos e só então procurar uma solução. Portanto, é melhor garantir que o conteúdo da sua documentação seja visível para os mecanismos de pesquisa e otimizado para eles, principalmente o Google, se você segmentar o mercado de língua inglesa.

Compatível com a marca

A aparência da Base de Conhecimento deve corresponder à linguagem de design e à marca de nossa empresa. Isso inclui cores, fontes, estilo de cabeçalho e rodapé, etc.

Escolher a plataforma de documentação certa é difícil!

Seguindo meu fluxo de descoberta natural, fui pedir conselhos ao Google. Desta vez, o Google não foi útil. Os resultados da pesquisa foram esmagadores. Não só que existem tantas opções no mercado, as soluções são inerentemente diferentes.

O Google não foi útil. Há tantas opções no mercado e as soluções são inerentemente diferentes.Tweet

Software de base de conhecimento como serviço

Existem soluções designadas de software de base de conhecimento desenvolvidas por empresas de suporte técnico como o Help Scout Docs e o Zendesk Help Center.

Bases de conhecimento estáticas

Os geradores de sites estáticos estão se tornando cada vez mais populares. Se você não estiver familiarizado com o conceito, a ideia geral é que a maioria dos sites é praticamente estática (incluindo seu blog WordPress) e não há motivo real para executar uma pilha de back-end esgotante como WordPress / PHP / MySql. Em vez disso, mova o trabalho pesado para um mecanismo de pré-implantação que gerará páginas HTML estáticas que podem ser hospedadas em CDNs sem sequer tocar em seus servidores. É econômico, escalável e seguro.

Existem centenas de geradores por aí, e motores como Jekyll e Hugo são altamente adotados entre a comunidade de desenvolvedores hardcore (por um bom motivo!).

Bases de conhecimento baseadas em WordPress

Encontrei mais de 20 plugins gratuitos da Base de Conhecimento no repositório WordPress.org, outra dúzia de plugins de documentação pagos no CodeCanyon e Google, e mais uma dúzia de temas da Central de Ajuda.

Sentindo confuso? Eu definitivamente fiz ¯\(°_o)/¯

Como você pode ver, opções demais. Decidi tentar outra estratégia – pedir uma recomendação de pessoas em cuja opinião eu confio. Sou membro de um grupo do Facebook chamado Vendendo Produtos WordPress, onde muitos dos meus amigos e pessoas líderes de produtos WordPress fazem parte. Tenho certeza de que 90% deles lidaram com o mesmo desafio antes de mim, então definitivamente valeu a pena tentar.

Antes de enviar minha pergunta, fiz uma pesquisa e encontrei um tópico de 2015, iniciado por Jean Galea do WP Mayor, que faz exatamente a mesma pergunta:

Impressionante! Eu refleti para mim mesmo. E então comecei a ler as respostas...

Adrian Labos está usando o Zendesk Help Desk
Pippin Williamson (Plugins Pippin) e Adam Pickering (Astoundify) estão usando o Help Scout Docs
Phil Derksen está usando o WordPress com o tema KnowHow
Dejan Markovic (Hype Social) está usando WordPress com plugin weDocs
Devin Walker (WordImpress) está usando o WordPress com CPT e o plugin ACF.
Ahmad Awais, que construiu o tema DocPress, diz que “manter um site de documentos com WordPress tornou-se ineficiente quando o número de produtos cresce” e agora ele está construindo uma Base de Conhecimento estática com o mecanismo de modelagem Jade.
Tom Hemsley (Mega Menu Plugin) recomendado para usar o WordPress com o plugin Heroic Knowledge Base.
Houve outras três respostas sobre plugins adicionais do WordPress por seus autores que fazem parte do grupo.

Como você pode ver, simplesmente não há consenso. Infelizmente, isso não foi muito útil.

Droga - é hora de alguma pesquisa ...

DICA: Como uma observação lateral, se você é um profissional de produtos na esfera do WordPress, recomendo que se inscreva neste grupo.

Inscreva-se e obtenha uma cópia gratuita do nosso

Livro de negócios de plug-in do WordPress

Exatamente como criar um próspero negócio de plugins WordPress na economia de assinaturas.

Grato pela assinatura!

- acabamos de enviar sua cópia do 'The WordPress Plugin Business Book' para .

Tem um erro de digitação no seu e-mail? clique aqui para editar o endereço de e-mail e enviar novamente.

Por que não escolhemos Help Scout Docs ou qualquer outra base de conhecimento SaaSy

Sou fã do Help Scout e nós os usamos para nosso sistema de tickets de suporte. Na verdade, sou amigo dos fundadores. Em 2011, estávamos trabalhando em uma mesa 2 e ficamos juntos por 4 meses, enquanto participamos do programa de aceleração Techstars em Boston. Isso foi quando o Help Scout era apenas Denny, Jared e Nick.

O Docs é uma solução de documentação bastante sólida e provavelmente a maneira mais fácil e rápida de seguir. Também é surpreendentemente personalizável. Mas como as outras plataformas SaaS, vem com falhas de SEO.

1. Configurar uma Base de Conhecimento, ou qualquer outro conteúdo, em um subdiretório ainda é significativamente melhor do que em um subdomínio em termos de classificação de pesquisa. Rand Fishkin, o fundador da MOZ (a empresa líder mundial em SEO) tem um ótimo vídeo de 2015 com casos de uso reais discutindo esse tópico.

Infelizmente, devido à maneira como os arquivos da zona DNS estão funcionando, não há como configurar um CNAME para um subdiretório.

Para garantir que não perdi nenhuma solução alternativa, entrei em contato com a equipe de suporte do Help Scout e aqui está a resposta que recebi:

“Odeio vir trazendo más notícias, mas não há como ter Docs em um subdiretório. Temos uma API para documentos que permite exportar seu site e hospedá-lo automaticamente, mas você teria que reconstruir parte da aparência e da funcionalidade: http://developer.helpscout.net/docs-api/
Receio que esta seja a única solução se você ainda quiser usar o Docs e tê-lo como um subdiretório.

2. Eu não verifiquei as outras soluções devido ao motivo anterior, mas o Help Scout Docs em particular, não inclui metadados Rich-Snippets para trilhas de navegação e pesquisa.

É assim que um resultado do Help Scout Docs se parece na SERP do Google (página de resultados do mecanismo de pesquisa):

Este é o resultado de uma página que tem metadados de rich snippets de trilhas de navegação:

E aqui está o resultado de uma página que tem metadados de rich snippets de pesquisa:

Não vou me aprofundar nesse tópico, mas em geral, metadados de rich snippets ajudam o mecanismo de pesquisa a entender melhor o conteúdo do seu site e sua estrutura. Os principais mecanismos de pesquisa do mundo: Google, Yahoo e Bing; pode traduzir esses dados em visuais que aumentam a CTR de pesquisa (taxa de cliques). Bottom line – você terá mais tráfego.

Também fiz um ping para Chris Mooney, cofundador da HeroThemes, uma empresa que se concentra apenas em soluções de base de conhecimento, e ele confirmou que o SEO é uma das principais razões pelas quais os clientes migram para sua solução de documentação local.

Apenas para enfatizar a importância do valor de SEO que você pode obter de uma documentação bem escrita, gostaria de compartilhar uma história rápida. Em 2011 me encontrei com Elad Eran, VP Customer Solutions da WiX. Eran orgulhosamente explicou que seu Software de Base de Conhecimento e Fóruns de Suporte são um dos principais catalisadores que ajudaram o WiX a ter uma classificação alta no Google e obter tráfego orgânico gratuito e de alta qualidade.

Software da Base de Conhecimento e Fóruns de Suporte são um dos principais catalisadores que ajudaram o WiX a ter uma classificação alta no Google e obter tráfego orgânico gratuito e de alta qualidade.Tweet

Se é bom para o WiX, deve ser bom para nós

Por que escolhemos o WordPress em vez de geradores de sites estáticos para nossa base de conhecimento

Os principais benefícios de ficar estático com um mecanismo como o Jekyll são velocidade, escalabilidade e segurança.

Podemos obtê-los com o WordPress? A resposta é – quase.

Como as páginas de documentação são estáticas (exceto para pesquisa), podemos instalar facilmente uma das dezenas de plugins de cache WordPress gratuitos, configurar o Nginx para servir os arquivos em cache diretamente do disco enquanto ignoramos o mecanismo WordPress e também usar um serviço CDN gratuito como CloudFlare para distribuir nossos arquivos em diferentes data centers ao redor do globo. Pode parecer complexo, mas na verdade não é, e explicarei tudo em breve.

Isso tornará nosso frontend de documentação absolutamente estático. Ele será dimensionado muito bem e será super rápido (porque é estático). Vlw! Vlw!

Em termos de segurança, bem, nada é perfeito, mas podemos tomar algumas precauções básicas usando alguns plugins gratuitos e algumas configurações no nível do servidor, que reduzirão a chance de ataque em 99,9%. Discutirei explicitamente isso daqui a pouco, incluindo todos os ingredientes.

Por outro lado, os contras da abordagem estática para nossa equipe foram:

Como equipe, teremos que adquirir um novo conjunto de habilidades técnicas, configurar um ambiente de desenvolvimento adicional e ter um processo de implantação contínua para garantir que a adição ou edição de arquivos não exija a intervenção de um desenvolvedor. É definitivamente factível, mas leva tempo.
A pesquisa é (principalmente) uma funcionalidade dinâmica, portanto, se ficarmos estáticos, teremos que implementar alguma API RESTful ou integrar um serviço de pesquisa de terceiros como o Algolia. Outra dor de cabeça para lidar.
O controle de versão não é um CMS. Por mais que eu ame o GitHub e o BitBucket, eles podem ser assustadores para pessoas que não entendem de tecnologia. Embora todos os membros de nossa equipe sejam desenvolvedores em sua formação, isso provavelmente mudará no futuro.

DICA: Vale a pena mencionar que durante minha pesquisa encontrei um projeto bacana chamado Prose.io que fornece uma edição de conteúdo WYSIWYG simples de arquivos GitHub e BitBucket.

Para resumir, podemos obter a maioria dos benefícios dos sites estáticos sem perder a flexibilidade do WordPress, mantendo o editor CMS fácil de usar e obtendo edição em tempo real sem um processo de implantação contínuo.

Por que escolhemos o plugin weDocs WordPress para nossa base de conhecimento?

Como mencionado anteriormente, eu tinha visto pelo menos 30 plugins e temas do WordPress para Bases de Conhecimento.

Como estamos administrando uma startup, avaliar todas elas não é viável. Então vamos tentar ir com a eliminação.

Os temas da Base de Conhecimento foram lançados!

Optamos por não usar nenhum tema de documentação porque a maioria deles usa o objeto de post padrão e a taxonomia de category para os artigos de documentação. Essa solução pode funcionar se você configurar uma instância dedicada do WordPress apenas para seu aplicativo Knowledge Base. Se você quiser ter todo o seu site na mesma instalação do WordPress, incluindo seu blog, as coisas podem e provavelmente ficarão confusas devido à mistura de tipos de conteúdo.

Yay – agora só temos mais 20 plugins para testar…

Testei quatro plugins gratuitos diferentes:

Base de Conhecimento CPT
Base de Conhecimento WP
Ajuda WP
weDocs

Rapidamente, descobri que todos eles aproveitam o WordPress CPT (Custom Post Types) e taxonomia personalizada para tags e categorias. A principal e única diferença significativa está na hierarquia da estrutura de dados.

Knowledge Base CPT e WP Knowledge Base são planos. Assim como nas postagens do blog, existem categorias, tags e artigos. Não há como associar um artigo a um artigo pai.

Assim, a estrutura de uma Base de Conhecimento com esses plugins serão categorias como seções e postagens como documentos.

 Categoria 1
↳ Documento 1
↳ Documento 2

Categoria 2
↳ Doc 3
↳ Documento 4

A vantagem dessa estrutura é que você pode associar um documento a várias categorias e fazê-lo aparecer em várias seções.

 Categoria 1
↳ Documento 1
...
Categoria 2
↳ Doc 3
↳ Documento 1

Por outro lado, a estrutura do artigo da Ajuda do WP e do weDocs é semelhante às páginas. Cada documento pode ser associado a qualquer outro documento como pai. Mas, ele só pode ser associado a um pai (não como uma categoria).

 Documento 1
↳ Documento 2
↳ Doc 3
↳ Documento 4
↳ Documento 5
↳ Doc 6

Existem dois benefícios para essa estrutura:

É mais estruturado. Isso força você a pensar onde exatamente é o local mais apropriado para adicionar o artigo de documentação.
As categorias não têm uma “ordem” específica. Portanto, não há uma maneira pronta para organizar categorias da maneira que é possível com postagens que têm uma propriedade menu_order .

As razões acima foram exatamente porque decidimos usar os plugins hierárquicos.

Ótimo – agora eu sei o tipo de estrutura de dados que precisamos para nossa documentação.

Então, passei um tempo lendo sobre dois plugins premium – wpDocs (a versão pro do WP Knowledge Base) e Heroic Knowledge Base. Ambos parecem visualmente impressionantes, mas…

Não consegui encontrar nenhuma diferença significativa entre esses dois plugins premium e os plugins gratuitos.
Ambos os plugins estão usando a estrutura de dados plana, que decidimos não usar.

Então, sim – provavelmente havia outros 10 plugins que eu nem olhei, mas o padrão era claro.

Decidimos usar o weDocs em vez do WP Help devido a vários motivos:

A interface do usuário de arrastar e soltar das configurações de administrador do weDocs é moderna, fácil de usar e visualmente atraente.
O WP Help não vem com taxonomia personalizada para os documentos. O que significa que as categorias e tags não são entregues prontas para uso.
A Ajuda do WP não oferece suporte a breadcrumbs.
O weDocs é fornecido com um conjunto de modelos personalizados que tornarão a documentação com boa aparência imediatamente (obviamente, é necessário alguma personalização da interface do usuário).
weDocs tem um fluxo de interface do usuário contínuo. No final de cada artigo, você pode navegar para o próximo na linha.

Vamos para a parte divertida – a implementação…

Instalando e Personalizando a Solução de Documentação do weDocs

Para começar, baixe e instale o weDocs diretamente do repositório WordPress.org:
https://wordpress.org/plugins/wedocs/

Agora é hora de fazer algumas personalizações:

Adicionando Metadados de Rich-Snippets de Breadcrumbs

Como não queríamos alterar o plugin real (se possível), usamos o template weDocs e o functions.php do tema para substituir a renderização padrão do breadcrumbs.

Copie /wedocs/templates/single-docs.php para /your-theme/wedocs/single-docs.php .
Adicione o seguinte código ao arquivo functions.php do tema:
Abra /your-theme/wedocs/single-docs.php e substitua a chamada para wedocs_breadcrumbs() por freemius_wedocs_breadcrumbs() .
Como também modificamos a estrutura HTML dos breadcrumbs para uma lista não ordenada ( <ul> ) para melhorar a semântica, adicione o seguinte código SASS ao seu tema:

Para concluir os Rich Snippets, você precisará adicionar o seguinte código à sua tag <body> :

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

Personalizando a estrutura de URL da base de conhecimento (links permanentes)

O weDocs é fornecido com a seguinte estrutura de permalinks padrão:
your-site.com/wordpress-root/docs/

Queríamos ter nossa documentação em freemius.com/help/documentation/, que deve ter uma classificação melhor em SEO ao pesquisar documentação. Também queríamos manter a página de “ajuda” para adicionar uma Central de Ajuda no futuro para que possamos usar estruturas de URL como /help/faq/ para uma página de perguntas frequentes e /help/forum/ para um fórum.

Poderíamos facilmente conseguir isso modificando as regras de reescrita do docs CPT no código do plugin. Mas como queremos evitar alterar o código do plugin, descobrimos uma maneira de fazer isso indiretamente no arquivo functions.php do tema:
Além disso, adicionamos suporte para trechos de artigos (precisamos disso para a próxima personalização), autor de documentos, campos personalizados e atributos de página. Importante: o weDocs é estruturado por padrão para a Base de Conhecimento de vários produtos. Assim, se você deseja ter a estrutura de /help/documentation/ , certifique-se de que o Doc de nível superior criado no back office seja chamado Documentation (slug deve ser documentation ).

Adicionando uma página inicial bonita à base de conhecimento do weDocs

Por padrão, o weDocs vem com um código de acesso que pode ajudá-lo a criar uma página inicial parecida com esta:

Não é ruim, mas eu pessoalmente prefiro o layout gerado pelo Help Scout Docs :

Ele fornece uma breve descrição sobre cada seção e parece mais visualmente atraente para mim. Primeiro, vamos criar os templates PHP adicionando docs-header-main.php e docs-sections.php na pasta /your-theme/wedocs/ . Você pode encontrar o código na seguinte essência: https://gist.github.com/vovafeldman/adbf1c071a08b7565df11d709b2f1240 Se você mergulhar no código do arquivo docs-header-main.php , você notará que eu também entrei na busca rica metadados de trechos. Agora, como o artigo /help/documentation/ é apenas mais um artigo na Base de Conhecimento, o modelo padrão que o WordPress usará é /wedocs/single-docs.php . Assim, precisamos adicionar o seguinte trecho de código ao topo desse arquivo, para carregar os novos modelos de seções quando o pai do artigo não estiver definido:

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

  return;
}

Tornando o weDocs compatível com dispositivos móveis / responsivo

Infelizmente, o weDocs não é fornecido com regras CSS responsivas. Veja como fica na base de conhecimento do weDevs (os desenvolvedores do weDocs):

Não vou me aprofundar no CSS, mas geralmente adicionamos consultas de mídia que:

Esconda as migalhas de pão.
Faça o conteúdo de largura total com um bom preenchimento.
Moveu a barra lateral de navegação e a pesquisa para a parte inferior, logo antes do rodapé.

Aqui está o resultado:

E aqui está a aparência da página de seções:

Excelente! Concluímos a customização do weDocs.

Usando Markdown em vez de HTML Rich Editing

Um dos requisitos iniciais da KB era a sustentabilidade – a capacidade de alterar facilmente o design e potencialmente uma plataforma (lembra?). Usar a edição de conteúdo rico em HTML é uma faca de dois gumes. Por um lado, é extremamente flexível e dá a liberdade de personalizar o estilo do conteúdo como desejar. Por outro lado, essa falta de estrutura permite que cada redator de conteúdo faça o que quiser. Isso não é sustentável, torna as alterações de design complexas e a migração ainda mais difícil. Por exemplo, usando <strong> vs. <b> . Ou usando tabelas baseadas em <table> vs. <div> . Essas são decisões relacionadas à sintaxe, e cada pessoa tem seu estilo de escrita único.

O que os redatores de conteúdo devem realmente focar é no conteúdo e na semântica, não no design.

Existem muitas linguagens de marcação com sintaxe de formatação de texto simples, embora o Markdown tenha sido a escolha natural, pois é amplamente usado por gigantes como GitHub, Atlassian e o próprio WordPress.

Escolhendo e instalando um plugin WordPress Markdown

Existem apenas dois plugins Markdown no repositório WordPress.org que possuem mais de 1.000 instalações ativas. WP-Markdown e JP Markdown. Sim, o Jetpack também possui um módulo Markdown, mas não fazia sentido instalar esse “monstro” apenas para um módulo. Inicialmente, instalei o WP-Markdown porque, com base nas capturas de tela, ele tinha a opção de selecionar facilmente quais tipos de postagem suportarão markdown. Infelizmente, o plugin não funcionou (a última atualização foi há mais de 3 anos), então acabamos não usando. Então, instalei o JP Markdown. O plugin funcionou, mas tinha algumas coisas que eu não gostei:

O markdown foi ativado automaticamente em todas as postagens e páginas.
A sintaxe de remarcação não foi preservada, foi automaticamente convertida em HTML estilizado:

Isso é ruim porque os dados são armazenados no banco de dados como HTML rico e não como markdown (verifiquei isso). Além disso, não adiciona nenhuma restrição na edição de HTML avançado. Portanto, se no futuro quisermos migrar para outro sistema, não há como exportar a remarcação.

Então encontrei o WP Markdown Editor que usa o módulo Markdown do Jetpack, e foi esse que acabamos usando. Mesmo que ainda tivéssemos que fazer algumas customizações:

O plug-in desativa a edição avançada de todas as postagens e páginas após a ativação. Queríamos nos livrar da edição rica apenas em nossas páginas de documentação.
O plug-in substitui o editor existente com seu próprio editor de remarcação para todas as postagens e páginas. Novamente, queríamos ter isso apenas em nossas páginas de documentação.

Você pode ver essas mudanças aqui:
https://github.com/Freemius/wp-markdown-editor/commit/706bce0c23943c82d102c67a09e18dac32c66207

Você pode baixar a versão bifurcada aqui (apenas algumas pequenas alterações):
https://github.com/Freemius/wp-markdown-editor

Em seguida, adicionamos uma função curta que registra o CPT de docs para dar suporte à edição de markdown e cancela o registro post e tipos de page para manter o editor HTML rico:

Por fim, tivemos que ajustar a funcionalidade de exportação padrão do WordPress para exportar o código de remarcação e não o conteúdo rico em HTML. Fizemos isso conectando-se ao the_content_export :
Incrível – nosso KB é alimentado por markdown e pode ser facilmente exportado.

Adicionando suporte ao YouTube e Vimeo Markdown

Os vídeos são uma parte essencial de qualquer Base de Conhecimento. Infelizmente, o Markdown não suporta vídeos. Felizmente, o WordPress torna super fácil adicionar shortcode e com algumas linhas de código. Enriquecemos nossa sintaxe Markdown para oferecer suporte à adição de vídeos do YouTube e do Vimeo:

Como bônus, tornamos o tamanho do vídeo responsivo e compatível com dispositivos móveis, e a adição de vídeos agora é intuitiva e direta com o ID do vídeo:
[youtube gj6aoYG4fUI]
[vimeo 185625717]

Adicionando suporte a códigos de acesso de chamadas agradáveis

A sintaxe padrão do Markdown suporta aspas em bloco, mas não vem com semântica para diferentes textos explicativos como dicas e avisos que não são obrigatórios, mas importantes para uma boa Base de Conhecimento.

Shortcodes do WordPress para o resgate novamente

E aqui está como fica no frontend:

Adicionamos o prefixo fs_ para evitar possíveis conflitos com plugins que possamos instalar no futuro.

Adicionando SyntaxHighlighter para Pretty Code

Nem o WordPress nem o WP Markdown Editor vêm com destaque de sintaxe de código. Como o Freemius é uma plataforma para desenvolvedores e nossa documentação vem com exemplos de código, a adição de realce de sintaxe foi crucial. Optamos por usar o SyntaxHighlighter Evolved, pois ele é desenvolvido pela Automattic, assim como o módulo principal do Markdown do Jetpack que é usado pelo plug-in WP Markdown Editor. Observar o código de renderização de markdown revela que eles realmente se integraram:

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

Impressionante! Certo? Infelizmente, parece que nada é perfeito fora da caixa e o código foi renderizado incorretamente. Ele estava atrapalhando as seções de código de várias linhas do Markdown, escapando caracteres especiais para suas entidades HTML correspondentes. Não apenas estava “quebrando” o código renderizado no frontend, mas também armazenando uma versão HTML com escape das partes do código do Markdown no banco de dados. E isso é ruim para a preservação de conteúdo e potencial exportação de dados. Assim, não tivemos escolha a não ser fazer alguns ajustes no código do plugin. Você pode ver as mudanças exatas aqui:
https://github.com/Freemius/wp-markdown-editor/commit/672695be8b29c57f7fa7ca580d29368b9e57af68

Agora temos uma base de conhecimento bonita, compatível com dispositivos móveis e baseada em Markdown, com suporte a vídeo, textos explicativos e realce de sintaxe de código. Sim!

Ainda precisamos torná-lo rápido e seguro (quase lá!).

Como tornamos nossa base de conhecimento do WordPress super rápida?

Escolhemos o WP Super Cache porque é amplamente popular (mais de 1 milhão de instalações ativas), desenvolvido e mantido pela Automattic, gratuito e relativamente fácil de configurar.

Adicionando permissões de disco

Crie uma pasta de cache gravável: mkdir /path/to/your/wordpress/wp-content/cache/ setfacl -Rm user:apache:rwx /path/to/your/wordpress/wp-content/cache Se a linha de permissões não funcionar, use o seguinte: chmod 777 /path/to/your/wordpress/wp-content/cache/

Ativando o cache

Habilite o cache adicionando o seguinte ao seu arquivo wp-config.php :

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

Agora tudo o que precisamos é ativar o cache, você pode fazer isso via WP Admin → Configurações → WP Super Cache: Não se esqueça de clicar no botão “Atualizar status” para salvar. Você pode verificar se o cache está funcionando abrindo qualquer página de front-end em seu site WordPress no modo de navegação anônima e verificando o código-fonte. Quando o WP Super Cache estiver funcionando, você deverá ver o seguinte comentário HTML na parte inferior do código-fonte da página:

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

<!-- super cache -->

Isso já é muito melhor do que servir as páginas sem qualquer cache. Mas isso ainda aciona toda a pilha de PHP, WordPress e MySql. Se quisermos tornar nosso site extremamente rápido, precisamos adicionar cache no nível do servidor.

Configurando o cache no nível do servidor

Se você estiver usando o Nginx, como nós, aqui está a configuração que usamos: WP Super Cache Regras de configuração do Nginx DICA: As regras de configuração do Nginx incluem várias regras if . Para economizar seu tempo valioso, certifique- if de que todas as regras estejam fora da diretiva de location , caso contrário, ele interromperá todo o processamento (perdi algumas horas descobrindo isso). Se você estiver usando o Apache, você pode encontrar as regras .htaccess mod_rewrite diretamente na página de instruções de instalação do plugin no WordPress.org: https://wordpress.org/plugins/wp-super-cache/installation/ A maneira mais fácil de testar o o cache no nível do servidor sem afetar seu site é seguir estas etapas:

Crie e publique um post fictício, defina o seguinte slug `dummy-cache-test`.
Carregue a página no modo de navegação anônima, certificando-se de que ela esteja armazenada em cache.

Adicione o seguinte código à parte superior do arquivo wp-config.php :

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

Depois de adicionar o código, recarregue a página no mesmo modo de navegação anônima. Se a página for carregada corretamente – o cache no nível do servidor está LIGADO Se você receber a mensagem “O cache do servidor está desativado”, algo está errado.

Não se esqueça de remover essa adição do arquivo wp-config.php , e também excluir o post fictício quando terminar. Fantástico – definimos o cache, todas as páginas agora são servidas diretamente dos arquivos HTML estáticos em cache, pulando PHP e WordPress.

Adicionando CDN

Mesmo que o KB já esteja em boa forma, cada visualização de página de um novo navegador irá “atingir” nosso servidor. Assim, quero eliminar isso adicionando mais uma camada – CDN.

Os benefícios claros da CDN são a distribuição global de data centers, alta disponibilidade e uma enorme redução nos recursos do servidor, especialmente quando as coisas estão estáticas. As páginas serão carregadas diretamente do CDN sem sequer “tocar” em nossos servidores.

Eu não posso falar o suficiente de CloudFlare. Estamos usando o CDN deles (e seus brindes extras) há anos, e o que há de insano nisso tudo - você pode usá-lo de graça! Isso mesmo – absolutamente grátis para 95% de seus recursos.

Apenas para dar um exemplo, digamos que você tenha uma página estática popular no site que recebe 5 milhões de visitas únicas diárias. Ignorando os servidores proxy e o cache do ISP, isso acionaria pelo menos 5 milhões de acessos diários ao seu servidor. Quando você usa um CDN como o CloudFlare, essa página estática só será carregada do seu site algumas vezes por dia (com base na frequência de limpeza do cache do CDN).

Aqui estão algumas estatísticas reais de um subdomínio que temos que serve apenas imagens:

Veja esses números – economizamos mais de 600 GB de largura de banda para nossos servidores. Se você configurar WordPress + WP Super Cache Plugin + Server Level Caching + CloudFlare CDN, provavelmente poderá usar um droplet DigitalOcean de $ 5 / mo sem problemas de dimensionamento!

Vamos fazer algumas contas juntos... WordPress é grátis, WP Super Cache é grátis, CloudFlare CDN é grátis... Oh – é apenas $5/mês para WordPress escalável. Louco né?!

Como personalizamos a pesquisa da base de conhecimento para fornecer dados em cache?

Por padrão, a estrutura de links permanentes de pesquisa do WordPress está usando uma string de consulta s= parâmetro para passar a consulta de pesquisa. Por um bom motivo, o WP Super Cache ignora as strings de consulta. Portanto, tivemos que fazer alguns pequenos ajustes na estrutura de URLs de pesquisa para que funcionasse:

Esta atualização altera a estrutura da URL para freemius.com/help/documentation/search/{query}/ que é armazenada em cache pelo WP Super Cache.

Estrondo! Até nossos resultados de pesquisa são armazenados em cache agora.

Como protegemos nossa base de conhecimento do WordPress?

A segurança é uma chave. A última coisa que qualquer empresa, especialmente uma startup, quer lidar é com uma violação de segurança. Pode prejudicar sua reputação, arriscar seu IP (Propriedade Intelectual) e levar horas, às vezes até dias, para recuperar o controle e os dados.

Muitos desenvolvedores adoram falar merda sobre o WordPress e dizer que é inseguro. Com base nos números – sim, eles provavelmente estão certos. Como o WordPress é a plataforma da web mais popular, também é o alvo número 1 para hackers, e os números fazem sentido – Duh…

O que eles não entendem é que o WordPress como plataforma é provavelmente um dos projetos mais seguros. 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).

Agora você

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.

Boa sorte!