Projeto Bokeh

Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:
Bokeh
Redator técnico:
vis_verborum
Nome do projeto:
Como criar, ler e compartilhar: como otimizar a documentação do Bokeh
Duração do projeto:
Duração padrão (3 meses)

Project description

Criação, leitura e compartilhamento: como otimizar a documentação do Bokeh

1. Com abstração

O Bokeh é uma ferramenta extremamente poderosa para criar visualizações interativas baseadas no navegador com Python. Ele tem uma base de usuários considerável (502 mil downloads mensais do Conda, 855 mil downloads do PyPi) e um grande número de colaboradores (455 no GitHub). Não é nenhuma surpresa que a extensa documentação de Bokeh seja cultivada organicamente. E, portanto, em alguns lugares, são inconsistentes, difíceis de acessar e complicados.

A temporada de documentos do Google oferece uma oportunidade única para uma revisão focada e revisão da estrutura e do conteúdo da documentação de Bokeh, além de garantir que a documentação, as ferramentas e os fluxos de trabalho associados sejam preparados para o futuro.

Codifiquei e documentei projetos de código aberto com Python e Sphinx (mais recentemente: PyZillow e PyPresseportal). Mas o que me torna uma participante único da Temporada de Documentos do Google é minha experiência em jornalismo: trabalhei em redações por mais de 13 anos, com muitos anos como editora-geral e defensor da mudança digital. Além das minhas funções jornalísticas, eu tinha responsabilidades cada vez maiores na criação e documentação de novas ferramentas digitais e guias de estilo, além de treinar a equipe da redação.

Após uma mudança recente da Europa para os EUA, decidi me aprofundar em novas maneiras de reunir meu entusiasmo por comunicação e programação. Achei que a escrita técnica é a combinação ideal das minhas habilidades e experiências em escrita e tecnologia. Nesta proposta, vou descrever como vou usar a temporada de documentos do Google para otimizar a documentação do Bokeh: tornando a criação e a contribuição para a documentação mais conveniente, tornando a leitura mais direta e simplificando o compartilhamento de informações na documentação com outras pessoas.

2. Situação atual

A documentação oficial da Bokeh consiste nestas unidades principais:

  • Documentação narrativa: guia de instalação, guia do usuário, guia do desenvolvedor, notas da versão
  • Galeria e demonstrações (exemplos interativos com o código-fonte)
  • Guia de referência (documentação baseada em docstrings)
  • Tutorial (ampla coleção de notebooks Jupyter, hospedados em mybinder.org)
  • Docstrings e ajuda de modelos para ambientes de desenvolvimento integrado
  • Exemplos e READMEs no repositório do projeto

Além disso, há muitas informações disponíveis no fórum de suporte Bokeh e no Stack Overflow, onde o desenvolvedor da Bokeh responde ativamente às perguntas dos usuários, bem como no blog da Bokeh no Medium.

A maioria das páginas da documentação da Web é criada com o Sphinx, usando várias extensões padrão e personalizadas do Sphinx. O Guia de referência, por exemplo, é gerado a partir de docstrings, usando extensões como "autodoc" e o "bokeh_autodoc" personalizado. Como é a natureza da documentação orgânica, ela contém redundâncias e inconsistências.

Uma das primeiras coisas que percebi ao analisar a documentação atual foi a falta de diretrizes de estilo claras para a redação da documentação. O Guia do desenvolvedor do Bokeh contém algumas instruções básicas. No entanto, este documento não contém muitas orientações sobre estilo, especialmente quanto à documentação que vai além de docstrings. Como consequência, problemas de estilo e estruturais dificultam o acesso às informações nos documentos, principalmente para iniciantes.

Exemplo:

A página de destino da documentação do Bokeh é curta e não inclui informações sobre todos os recursos disponíveis. Nenhuma menção à extensa biblioteca de docstrings e funções de ajuda do modelo, os fóruns de suporte, as demonstrações ou o blog do Medium. Isso também dificulta que novos usuários comecem a usar o Bokeh.

3. Objetivos

Para utilizar a fase de desenvolvimento de documentos de 11 semanas de forma mais eficiente, vou me concentrar em três elementos principais:

3.1. Melhorar a criação dos documentos

A maior parte da documentação do Bokeh é escrita por colaboradores que a incluem como parte de solicitações de envio para novas funcionalidades e correções de bugs. Embora usemos parte da fase de desenvolvimento de documentos para editar e refatorar os documentos existentes, vou enfatizar a preparação para o futuro dos fluxos de trabalho de criação e manutenção da documentação: os colaboradores devem manter um alto padrão consistente de documentação.

Vou garantir isso com duas abordagens:

  • Vou criar um conjunto de diretrizes de estilo simples e práticas para incluir no guia para desenvolvedores atual. Elas tratam do estilo, da gramática e da estrutura. Além disso, vou usar canais de comunicação internos, como o Slack, para garantir que os colaboradores do Bokeh estejam cientes das diretrizes de estilo. Também oferecerei treinamento individual e sessões de perguntas e respostas para a equipe.
  • Vou trabalhar com a equipe principal para encontrar um conjunto ideal de ferramentas para controle de qualidade da documentação, que vai ser adicionado aos fluxos de trabalho existentes da Bokeh para PRs (solicitações de envio) e CI (integração contínua). Dependendo dos requisitos da equipe, isso pode significar adicionar ferramentas como pydocstyle, proselint ou sphinxcontrib-spsell ao pacote de testes, configuração pré-confirmação ou ações do GitHub. Adicionei uma prova de conceito funcional às ações do GitHub de um dos meus projetos de código aberto.

3.2. Melhore a leitura dos documentos

O objetivo de uma boa documentação é permitir que usuários atuais e potenciais encontrem exatamente as informações certas e possam usá-las da maneira mais eficiente possível.

Os principais fatores para a usabilidade de um texto são o estilo e a estrutura: redigir a documentação em um estilo claro e consistente permite que os leitores coletem informações rapidamente, sem distrações e linguagem supérflua. Com uma estrutura direta e transparente, fica mais fácil encontrar informações relevantes rapidamente.

Vou me concentrar nessas duas áreas, com ênfase na usabilidade para novos usuários. Isso incluirá uma revisão completa da documentação da narrativa, centrada no Guia do usuário. Também revisarei a página de destino da documentação para abordar com mais clareza os diferentes públicos-alvo e garantir que todos os usuários possam encontrar os recursos certos com rapidez.

Assim como ao melhorar a criação de documentos descritos acima, vou me concentrar em estabelecer uma base para melhorias futuras e manter altos padrões continuamente para a documentação de Bokeh.

3.3. Melhorar o compartilhamento dos documentos

O Bokeh está acontecendo cada vez mais nas plataformas de terceiros. Muitas dessas plataformas usam metadados, como o OpenGraph do Facebook, para incluir visualizações detalhadas de links. O OpenGraph é usado por serviços como Facebook, Twitter, LinkedIn, Slack e iMessage. O fórum Discourse do Bokeh também usa o OpenGraph para renderizar visualizações de links.

Para usar essa tecnologia, adicionarei metadados às páginas da Web geradas pelo Sphinx da Bokeh, conforme descrito no problema 9792. A maneira mais eficiente seria usar uma extensão dedicada do Sphinx. Alguns dias atrás, a primeira versão de uma extensão Sphinx para dados do OpenGraph foi publicada no GitHub. Usarei algumas da fase de desenvolvimento de documentos para ajudar a melhorar esta extensão para uso com a documentação do Bokeh.

Também criei uma prova de conceito que estou usando com sucesso em um dos meus projetos de código aberto, o PyPresseportal. Esta extensão coleta automaticamente informações relevantes como título, descrição, imagem e URL. Em seguida, insere essas informações no código HTML gerado pelo Sphinx como tags OpenGraph.

Uma próxima etapa no desenvolvimento dessa extensão seria introduzir diretivas personalizadas para definir manualmente os metadados do OpenGraph (semelhante às diretivas "meta" existentes do docutil). Os metadados gerados automaticamente seriam usados apenas como substitutos, caso não houvesse dados inseridos manualmente disponíveis.

O suporte a dados estruturados é muito mais complexo, então vou me concentrar principalmente em incluir metadados de alta qualidade do OpenGraph para a documentação de Bokeh. Ao mesmo tempo, todo o trabalho envolvido no suporte ao OpenGraph estabelecerá as bases para o suporte aos Dados estruturados.

Os membros das comunidades Sphinx e ReadTheDocs demonstraram interesse em desenvolver extensões para o OpenGraph e os dados estruturados (nas edições 1758 e 5208, por exemplo), e trabalharei em conjunto com eles.

4. Resultados finais

Para resumir, estes são os resultados que espero da temporada de Documentos:

  • Diretrizes de estilo de documentação para colaboradores do Bokeh
  • Revisão dos fluxos de trabalho de PR e CI para incluir o controle de qualidade automatizado da documentação
  • Guia do usuário editado e reestruturado
  • Página de destino da documentação revisada
  • Metadados do OpenGraph incluídos nas páginas da Web da documentação e em uma extensão Sphinx em funcionamento

Além disso, manterei um "doclog" para documentar minha jornada pela temporada de documentos do Google em meu site pessoal/Medium ou blog do Bokeh no Medium. Isso também vai servir de base para o relatório do projeto para o Google. Farei todo o trabalho de forma transparente, na forma de problemas do GitHub e solicitação de envio, sempre que possível.

5. Cronograma

Antes da fase de criação de vínculo com a comunidade: já participo ativamente de várias discussões no repositório do GitHub do Bokeh e estive em contato com Bryan Van de Ven e Pavithra Eswaramoorthy, mentores do Bokeh para a Temporada de Documentos do Google. Permanecer ativo na conversa sobre Bokeh e também me familiarizar ainda mais com Bokeh, construindo e publicando visualizações.

Fase de vínculo comunitário (17/08 a 09/13):

  • Conhecer a equipe principal e refinar o plano do projeto em troca de mentores.
  • Estabelecer uma programação e canais de comunicação para relatórios e feedback regulares com mentores
  • Seja ativo no Slack do Bokeh para informar todos os colaboradores interessados da Bokeh sobre a temporada de documentos do Google e as metas para a fase de desenvolvimento de documentos
  • Reunir feedback dos colaboradores do Bokeh para refinar ainda mais o plano para a fase de desenvolvimento do documento

Fase de desenvolvimento dos documentos

Semana 1, 14/09 a 20/09:

  • Começar a auditar e editar a documentação da narrativa
  • Começar o rascunho das diretrizes de estilo

Semana 2, de 21 a 27/09:

  • Continuar o trabalho nas diretrizes de estilo
  • Continuar editando a documentação da narrativa
  • Começar a revisar a página de destino da documentação

Semana 3, 28/09 a 04/10:

  • Finalizar as diretrizes de estilo
  • Finalizar a página de destino da documentação

Semana 4, 05/10 a 11/10:

  • Finalizar a edição da documentação da narrativa
  • Discutir com a equipe principal da Bokeh sobre a integração de ferramentas para controle de qualidade de documentos nos fluxos de trabalho de PR/CI

Semana 5, 12/10 a 18/10:

  • Agende uma sessão de perguntas e respostas com colaboradores do Bokeh no Slack para discutir diretrizes de estilo, melhorias na documentação narrativa e fluxos de trabalho PR/CI
  • Começar a desenvolver minha prova de conceito atual para metadados do OpenGraph em uma extensão Sphinx implantável
  • Revisar as diretrizes de estilo com base no feedback da sessão de perguntas e respostas com colaboradores do Bokeh

Semana 6, 19/10 a 25/10:

  • Começar a testar ferramentas de controle de qualidade de documentos nos fluxos de trabalho de RP e CI
  • Continuar o desenvolvimento da extensão Sphinx para metadados

Semana 7, 26/10 a 01/11:

  • Teste da extensão Sphinx
  • Segunda sessão de perguntas e respostas com colaboradores do Bokeh no Slack
  • Revisar as entregas com base no feedback da segunda sessão de perguntas e respostas

Semana 8, 02/11 a 08/11:

  • Implante a extensão Sphinx e publique documentação narrativa aprimorada e página de destino da documentação

Semana 9, de 09/11 a 15/11:

  • Implante ferramentas de controle de qualidade de documentos nos fluxos de trabalho de relações públicas e CI
  • Atualizar e publicar o guia para desenvolvedores para incluir diretrizes de estilo e adições aos fluxos de trabalho de PR e CI

Semana 10, 16/11 a 22/11:

  • Finalizar as tarefas restantes

Semana 11, 23/11 a 29/11:

  • Começar a escrever o relatório do projeto
  • Começar a escrever a avaliação do projeto

Fase de finalização do projeto

Semana 12, 30/11 a 05/12:

  • Finalizar e enviar relatório do projeto

Semana 13, 03/12 a 10/12:

  • Finalizar e enviar a avaliação do projeto

Após o fim da temporada de documentos do Google:

  • Espero estar envolvido no desenvolvimento do Bokeh e continuar trabalhando na documentação dele.
  • Planejo continuar o desenvolvimento de uma extensão Sphinx para metadados do OpenGraph/dados estruturados.
  • Espero usar minha formação em jornalismo e minha rede existente para promover o Bokeh como uma ferramenta no jornalismo de dados. Por exemplo, escrevendo sobre o Bokeh com um público jornalístico em mente ou oferecendo palestras em conferência sobre o uso desse bokeh em contextos jornalísticos.

6. Sobre mim

Sou originalmente jornalista com formação em notícias de TV, on-line e rádio. Trabalhar como editora-chefe e repórter em notícias digitais e na TV me proporcionou anos de experiência em escrita e edição. Ao mesmo tempo, trabalhei em vários projetos que promovem a transformação digital e a automação. Escrevi vários manuais sobre fluxos de trabalho e ferramentas digitais, além de guias de estilo e estratégias de comunicação para marcas de notícias digitais. Também treinei os membros da equipe para usar essas ferramentas.

Sempre me interessei pelas interseções entre comunicação e tecnologia. Um mundo totalmente novo se abriu quando aprendi a programar em Python: por exemplo, sou capaz de fazer análises e visualizações de dados para o jornalismo de dados. Aprender a programar também me permitiu trabalhar ativamente com engenheiros de software no desenvolvimento de ferramentas digitais para fluxos de trabalho de redação.

Os manuais e documentos que escrevi em meu trabalho anterior, infelizmente, não são públicos. Portanto, agora estou me concentrando em me envolver mais com projetos de código aberto (veja exemplos abaixo). Baseei meu trabalho em redação técnica em guias de estilo, como o Guia de estilo da documentação do desenvolvedor do Google e o Guia de estilo da Microsoft. Uso o GitHub, o Slack e o Linux com frequência. Escrevo documentações narrativas, bem como docstrings e dicas de digitação, usando ferramentas como Sphinx, Mypy e Sphinx autodoc.

No momento, trabalho como freelancer. Meu cronograma oferece a flexibilidade necessária para trabalhar na documentação de Bokeh por cerca de 25 horas por semana durante a fase de desenvolvimento do documento. Trabalho no fuso horário do Pacífico, mas fico feliz em atender aos cronogramas e necessidades da equipe.

7. Exemplos recentes de documentação de código aberto

  • PyZillow: é um wrapper do Python para a API do site de imobiliárias Zillow.com. Além de fornecer código e atuar como um dos mantenedores de código, escrevi a documentação completa. Usei o Sphinx para a documentação da narrativa e para a referência do módulo. Criei a referência do módulo com o autodoc da extensão Sphinx, com base nas docstrings que adicionei ao código.

  • PyPresseportal: o PyPresseportal é um wrapper do Python para a API do site presseportal.de. O site presseportal.de é um dos maiores distribuidores de comunicados à imprensa e anúncios de relações com investidores na Alemanha. Por exemplo, quase todos os policiais e bombeiros usam esse serviço para distribuir comunicados à imprensa. Depois de usar a API por muitos anos como jornalista, decidi desenvolver uma interface em Python para acessar os extensos recursos de dados do site como objetos do Python. Escrevi o código e toda a documentação baseada no Sphinx.