Toda a documentação de produto voltada para o público do Zendesk é publicada nessa central de ajuda da Zendesk. Apesar de a maioria das equipes na Zendesk criar conteúdo diretamente na central de ajuda, a equipe de Documentação cria e mantém a documentação de produto offline nos arquivos de origem em DITA. A DITA (Document Information Typing Architecture) é um modelo de dados baseado em XML para fins de autoria e publicação de conteúdo.
Este artigo abrange os seguintes tópicos:
O que é DITA?
DITA é um padrão do setor para criar e manter conjuntos de documentos em larga escala. Jacquie Samuels da techwhirl.com descreve o problema e tenta solucioná-lo:
Escrever o conteúdo em Word, e-mail, PowerPoint, WordPress, HTML, InDesign, FrameMaker ou em qualquer outro formato é igual a escrever na pedra. Seu conteúdo fica praticamente engessado e perde utilidade. O conteúdo sem utilidade não pode ser facilmente reutilizado ou usado para outra finalidade, o que é ineficiente e custoso.A DITA é uma forma de escrever e armazenar seu conteúdo para que você possa gerenciá-lo como um ativo. Ela aproveita a linguagem XML (Extensible Markup Language) para tornar seu conteúdo inteligente, versátil, gerenciável e portátil.
Por exemplo, o conteúdo que está em DITA pode ser publicado totalmente com marca em PDF, HTML, RTF, PowerPoint e formatos para dispositivos móveis sem precisar copiar e colar nada entre os arquivos.
(Fonte: What Is DITA? na TechWhirl)
Além de separar o conteúdo do formato, os outros benefícios do DITA para a equipe de documentação da Zendesk incluem:
- Cria disciplina sobre a estrutura do conteúdo. O arquivo em DITA tem formato XML. Se a estrutura é inválida, a ferramenta não permite que façamos nada com ela.
- Permite mover o conteúdo com mais facilidade. É só arrastar um nó de um tópico de um lugar para outro na estrutura.
- Permite reutilizar o conteúdo com importação de blocos de conteúdo em vários artigos.
- Normalmente não publicamos PDFs, mas se o fizermos, usamos os arquivos de origem em DITA.
A ferramenta de autoria em DITA que usamos é a Oxygen XML Author. Além de seu ambiente robusto de autoria, contamos com um host com outros recursos, incluindo pesquisa em arquivos, comparação de arquivos, rastreamento de alterações e transformações em HTML. Outras ferramentas de autoria em DITA incluem Framemaker, Arbortext e XMetal entre outras.
Como publicar na central de ajuda
Usamos a ferramenta Author para criar e atualizar o conteúdo em arquivos de origem em DITA. Quando a publicação estiver pronta (normalmente no lançamento ou na atualização de um recurso de produto), transformamos o DITA em HTML e colamos o HTML de origem em um editor de código de artigo no Guide. O processo não é elegante, mas ganha no quesito simplicidade.
Às vezes precisamos atualizar muitos arquivos em pouco tempo. Por exemplo, quando a Zendesk simplificou os preços e a marca, centenas de artigos alterados precisaram ser publicados até as 8h no fuso horário do Pacífico de uma determinada data. Semanas antes do prazo, os redatores atualizaram os arquivos de origem em DITA, então fizemos a transformação em lote dos arquivos e os subimos para a central de ajuda usando a API do Zendesk. A publicação dos arquivos foi muito rápida.
A ferramenta de publicação em lote que usamos é um software livre no Github para uso de qualquer pessoa. Consulte https://github.com/chucknado/zpu. Para obter instruções de como usá-la, consulte o arquivo readme em https://github.com/chucknado/zpu/blob/master/README.md.
Como gerenciar arquivos
Armazenamos os arquivos em DITA no Google Drive da equipe, que sincroniza todos os arquivos automaticamente no computador de cada redator. Os redatores sempre têm as versões mais recentes ao seu alcance. Quando um redator salva as alterações em um artigo, as alterações são propagadas imediatamente para os computadores dos outros redatores devido à sincronização do Drive da equipe. O Drive da equipe inclusive mantém as alterações dos últimos 30 dias. Voltamos a ressaltar que a intenção é simplificar o processo.
Armazenamos também as imagens no Google Drive da equipe e fazemos o carregamento delas no servidor de arquivos do Amazon S3 para disponibilizá-las para o público. Todas as imagens em nossos artigos podem ser baixadas do seu navegador do S3, não da central de ajuda. O serviço Amazon S3 simplifica o gerenciamento de imagens.
Como publicar artigos localizados
O idioma padrão de nossas centrais de ajuda é o inglês. Publicamos as documentações do produto também nos idiomas alemão, espanhol, francês, japonês, coreano e português do Brasil.
No momento da transferência para a localização, usamos a API da central de ajuda para baixarmos os artigos selecionados que estão em inglês da central de ajuda e gravá-los em arquivos HTML. Usamos a API da Amazon para baixar as imagens do artigo do nosso bucket do Amazon S3. Colocamos os arquivos em pacotes e transferimos para nosso prestador de serviço de localização. Após o prestador entregar as traduções, carregamos os artigos e as imagens com as APIs da central de ajuda e da Amazon.
O cliente de API que usamos para gerenciar os arquivos de transferência chama-se ZLO (Zendesk localization tools), e foi criado internamente pela equipe de documentação. O cliente do ZLO é um software livre e está disponível no Github em https://github.com/chucknado/zlo. Para ler mais sobre ele, acesse a documentação no Github.