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. O DITA (Darwin Information Typing Architecture) é um modelo de dados baseado em XML para fins de autoria e publicação de conteúdo. Basicamente, os arquivos DITA são arquivos XML de texto sem formatação.
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. É feito para publicar conteúdo em vários canais a partir de uma fonte única. 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, validação e transformações em XHTML. Outras ferramentas de autoria em DITA incluem Framemaker, Arbortext e XMetal entre outras.
Como criar e publicar artigos
Os redatores usam Oxygen XML Author para criar ou atualizar conteúdo nos arquivos DITA. Como o DITA foi criado para permitir a publicação em vários canais a partir de uma fonte única, os arquivos de texto DITA não contêm estilos. Tudo o que contêm é o conteúdo estruturado. Para o canal web, todos os estilos são fornecidos por planilhas de estilo CSS externas, não pelo DITA. Em nosso caso, todos os estilos são fornecidos pelas planilhas de estilo em nosso tema do Guide.
Quando estamos prontos para publicar (geralmente ao mesmo tempo em que um recurso de produto é lançado ou atualizado), usamos o Author para transformar o arquivo DITA em XHTML, que é uma versão mais rígida do HTML. Então publicamos o XHTML na central de ajuda usando a API da Central de Ajuda.
A partir da versão 24, o Oxygen XML Editor inclui um cenário de transformação incorporado que pode publicar tópicos DITA em saída XHTML e carregá-los diretamente como artigos em uma central de ajuda do Zendesk. Consulte DITA Map Publishing na ajuda do XML Editor. Você também pode assistir ao vídeo Publishing Content to Zendesk Help Center na ajuda do XML Editor.
À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 usamos o Author para fazer a transformação em lote dos arquivos. Os arquivos são publicados na central de ajuda usando a API da Central de Ajuda. A publicação dos arquivos foi muito rápida.
Como gerenciar arquivos
Usamos o GitHub para gerenciar nossos arquivos DITA. Antes de criar ou atualizar um artigo, um redator cria uma ramificação em nosso repositório, faz as alterações e cria a solicitação de pull. A solicitação de pull é revisada pelos outros redatores na equipe. Isso tem o benefício adicional de dar aos redatores a oportunidade de revisar o trabalho uns dos outros.
Armazenamos as imagens no Amazon S3, ou Amazon Simple Storage Service, um serviço de armazenamento em nuvem dimensionável fornecido pela Amazon Web Services (AWS). Todas as imagens em nossos artigos são enviadas para 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, português do Brasil, italiano e chinês simplificado.
Quando uma localização precisa ser entregue, usamos a API da central de ajuda para baixar da central de ajuda os artigos selecionados em inglês e gravá-los em arquivos HTML. Usamos a API da AWS para baixar as imagens do artigo do nosso bucket do Amazon S3. Colocamos as imagens e os arquivos HTML em pacotes e os enviamos para nosso prestador de serviço de localização. Após o prestador entregar as traduções, carregamos os artigos e as imagens com a API da Central de Ajuda e a API da AWS.
5 comentários
Entrar para comentar.