Melhorando as ações na documentação de referência do Google com o novo tema Typedoc Neo

Nick Felker em Google Developers Follow Abr 9 · 5 min ler

Quando a biblioteca Actions on Google Node.js migrou da versão 1 para a versão 2 , ela foi reconfigurada em TypeScript, um superconjunto da linguagem de programação JavaScript que é transpilada para JavaScript. Como parte desse desenvolvimento, usamos uma ferramenta chamada TypeDoc para gerar documentação de referência.

Quando começamos a hospedar os documentos, vários problemas com o tema apareceram. O tema padrão dificultou o acesso rápido à documentação que os desenvolvedores queriam e comecei a elaborar um módulo aprimorado que proporcionaria uma melhor experiência ao usuário.

Recentemente este trabalho foi lançado como um projeto de código aberto no GitHub chamado Typedoc Neo . Qualquer desenvolvedor pode obter a biblioteca através do npm executando npm install typedoc-neo-theme .

Nesta postagem do blog, analisarei algumas das grandes mudanças e como elas facilitam a leitura da nossa documentação de referência para o Actions on Google developers.

Navegabilidade e navegação

O tema original tinha dois conjuntos de índices, ambos alinhados à direita da página. O primeiro foi o índice para um módulo específico, listando as classes, interfaces e outros recursos usando iconografia. O segundo foi a navegação global, permitindo que um desenvolvedor encontre todos os módulos.

A concatenação de ambas as listas dificultou a leitura e a localização da página ou do conteúdo desejado. A biblioteca Actions in Google, em particular, tinha vários módulos que não eram importantes para desenvolvedores externos, o que significava que vários dos itens da lista eram inúteis. As páginas que eram mais importantes tinham que ser encontradas clicando em vários links no conteúdo.

No tema revisado, as tabelas são divididas em duas. O lado esquerdo exibe uma navegação global e o lado direito exibe a navegação da página.

O índice no lado esquerdo é personalizável. Com base no que é mais importante para os desenvolvedores, criamos uma lista de páginas com base em nossa configuração typedoc.json . Você pode ver como criamos uma estrutura aninhada para navegação no snippet abaixo:

Outra novidade é a adição de vários links no topo da página. Estes podem apontar para outra documentação. Nesta página, ele replica as páginas de nível superior na documentação do Actions on Google , facilitando para os desenvolvedores encontrar outros conteúdos úteis para a criação de suas ações.

Para fazer isso, adicionamos vários links à nossa configuração typedoc.json, conforme mostrado no snippet abaixo:

Legibilidade

No tema antigo, a navegação da página tinha ícones ao lado do nome de cada recurso. Para saber se um recurso do módulo era uma interface ou uma classe, você precisava examinar o ícone e consultar uma legenda na parte inferior da página. Isso dificultou o acompanhamento.

No menu à direita revisado, os ícones foram desenfatizados e os títulos no topo permitem que o leitor saiba quais são as classes e quais são as interfaces. A adição deste texto torna o módulo mais fácil de entender sem a necessidade de conhecimento esotérico. O menu também é pegajoso, por isso, é fácil navegar mesmo quando se rola a página.

Outro desafio de legibilidade estava em torno da cor do link padrão, que era azul claro. Este azul tem uma taxa de contraste de 2,56, que pode ser difícil de ler para aqueles que não têm boa visão.

Documentação de referência original Documentação de referência atual

A nova cor de link padrão é a cerceta, que tem uma taxa de contraste mais alta que ultrapassa o nível AA padrão. É mais fácil de ler e coloca menos tensão nos seus olhos. Para material de referência, que os desenvolvedores podem consultar com frequência, essa é uma melhoria útil.

Procurar

A pesquisa foi outra área que poderia ser melhorada. Ao procurar por um recurso em particular, como um BasicCard , os desenvolvedores podem descobrir tipos e parâmetros internos que poderiam enganá-los sobre como implementá-lo.

Embora poder ser útil acessar esses tipos internos, desejamos direcionar os desenvolvedores para páginas que seriam mais relevantes para eles.

Ao analisar novas formas de visualizar os resultados da pesquisa, o site do desenvolvedor Android foi tomado como uma inspiração. A pesquisa por uma palavra-chave comum fornecerá uma série de páginas com metadados adicionais, como o nível da API e a categoria do conteúdo. Essa funcionalidade de pesquisa pode ser útil para encontrar a página correta e discutimos como levar o mesmo tipo de recurso aos nossos documentos de referência.

No novo tema, um conjunto de resultados de pesquisa foi marcado como de alta prioridade. Esses resultados aparecem com um rótulo adicional, como "Rich Response". Outros resultados foram desprivilegiados. Enquanto eles ainda aparecem, eles não são enfatizados para chamar a atenção para outros resultados.

Nós especificamos expressões regulares para as páginas que queremos destacar, conforme mostrado no snippet abaixo:

Conclusão

O tema Typedoc Neo continuará a ser desenvolvido conforme necessário para proporcionar uma experiência de documentação de alta qualidade aos desenvolvedores para a biblioteca Actions on Google e outras bibliotecas que os desenvolvedores possam criar.

Para visualizar o projeto no GitHub, que inclui documentação sobre como usá-lo e criá-lo você mesmo, acesse https://github.com/google/typedoc-neo-theme . Também está disponível via npm .

Se você estiver interessado em navegar pela documentação do Actions on Google, que está usando o novo tema, acesse https://actions-on-google.github.io/actions-on-google-nodejs/ .