Projeto Bokeh

Esta página contém os detalhes de um projeto de escrita 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:
Criar, ler e compartilhar: como otimizar a documentação da Bokeh
Duração do projeto:
Duração padrão (3 meses)

Project description

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

1. Com abstração

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

A temporada de documentos do Google oferece uma oportunidade única para uma revisão e revisão focadas na estrutura e o conteúdo da documentação de Bokeh e para 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 um participante único da Season of Docs 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 uma responsabilidade cada vez maior 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 recente mudança da Europa para os EUA, decidi explorar novas maneiras de reunir meu entusiasmo por comunicação e programação. Achei que a escrita técnica é a combinação ideal de minhas habilidades e experiências em escrita e tecnologia. Nesta proposta, vou mostrar como 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 convenientes, tornando a leitura mais direta e facilitando 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 (coleção abrangente 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, muitas informações estão 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 Medium da Bokeh.

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 "bokeh_autodoc" personalizado. Assim como é a natureza da documentação desenvolvida organicamente, ela contém redundâncias e inconsistências.

Uma das primeiras coisas que observei ao analisar a documentação existente foi a falta de diretrizes claras de estilo 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 sobre documentação que vai além de docstrings. Como consequência, problemas de estilo e estrutural dificultam o acesso às informações nos documentos, especialmente para iniciantes.

Exemplo:

A página de destino da documentação (em inglês) do Bokeh é bem curta e não inclui informações sobre todos os recursos disponíveis. A grande biblioteca de docstrings e funções de ajuda de modelos, os fóruns de suporte, as demonstrações ou o blog do Medium não são mencionados. Isso também dificulta que novos usuários comecem a usar o Bokeh.

3. Metas

Para utilizar a fase de desenvolvimento de documentos de 11 semanas com mais eficiência, 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 eu use parte da fase de desenvolvimento de documentos para editar e refatorar os documentos existentes, vou enfatizar a preparação dos fluxos de trabalho para a criação e manutenção da documentação: a manutenção futura de um padrão deve ser o mais fácil possível para os colaboradores.

Para garantir isso, use duas abordagens:

  • Criarei um conjunto de diretrizes de estilo práticas e simples a serem incluídas no guia para desenvolvedores existente. Essas diretrizes tratam de estilo, gramática e 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 individualizado e sessões de perguntas e respostas para a equipe.
  • Trabalharei com a equipe principal para encontrar um conjunto ideal de ferramentas de controle de qualidade da documentação, que será adicionado aos fluxos de trabalho existentes da Bokeh para RPs (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-spuring para o pacote de testes da Bokeh, configuração de 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 facilmente as informações certas e que possam usá-las da forma mais eficiente possível.

Os principais fatores para a usabilidade de um texto são seu estilo e estrutura: redigir uma 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 narrativa, centrada no Guia do usuário. Também revisarei a página de destino da documentação para abordar mais claramente diferentes públicos-alvo e garantir que todos os usuários possam encontrar os recursos certos rapidamente.

Assim como para melhorar a criação dos 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. Melhore o compartilhamento dos documentos

Cada vez mais discussões sobre o Bokeh estão acontecendo em 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 da Bokeh também usa o OpenGraph para renderizar visualizações de links.

Para usar essa tecnologia, adicionarei metadados às páginas da Web geradas pela Sphinx do Bokeh, conforme descrito no problema No 9792. A maneira mais eficiente seria usar uma extensão Sphinx dedicada. Alguns dias atrás, a primeira versão de uma extensão Sphinx para dados do OpenGraph foi publicada no GitHub (em inglês). 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. Essa extensão coleta automaticamente informações relevantes, como título, descrição, imagem e URL. Em seguida, ele 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" 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 do Bokeh. Ao mesmo tempo, todo o trabalho de 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 dados estruturados (nas questões 1758 e 5208, por exemplo), e trabalharei com eles em estreita colaboração.

4. Resultados

Para resumir, estes são os resultados esperados na temporada de Documentos:

  • Diretrizes de estilo da documentação para colaboradores do Bokeh
  • Revisão dos fluxos de trabalho de RP e CI para incluir 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 de documentação e em uma extensão Sphinx funcional

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

5. Cronograma

Antes da fase de conexão com a comunidade: já estou participando ativamente de várias discussões sobre o 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 vou me familiarizar ainda mais com Bokeh, construindo e publicando visualizações.

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

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

Fase de desenvolvimento do documento

Semana 1, de 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/09 a 27/09:

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

Semana 3, 28/09 a 4/10:

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

Semana 4, de 5/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, de 12/10 a 18/10:

  • Agende uma sessão de perguntas e respostas com os colaboradores da Bokeh no Slack para discutir diretrizes de estilo, melhorias na documentação narrativa e fluxos de trabalho de PR/CI
  • Começar a desenvolver minha prova de conceito existente 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 da Bokeh

Semana 6, de 19/10 a 25/10:

  • Começar a testar ferramentas de controle de qualidade de documentos em 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 9/11 a 15/11:

  • Implante ferramentas de controle de qualidade de documentos em fluxos de trabalho de RP e CI
  • Atualizar e publicar o guia para desenvolvedores para incluir diretrizes de estilo e adições aos fluxos de trabalho de RP 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, de 30/11 a 05/12:

  • Finalizar e enviar o relatório do projeto

Semana 13, 3 a 10/12:

  • Finalizar e enviar a avaliação do projeto

Após o fim da temporada de Documentos Google:

  • Espero continuar 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 experiência em jornalismo e minha rede atual para promover o Bokeh como uma ferramenta de jornalismo de dados. Por exemplo, escrevendo sobre o Bokeh com um público jornalístico em mente ou oferecendo palestras sobre o uso desse recurso em contextos jornalísticos.

6. Sobre mim

Sou originalmente jornalista e tenho experiência com TV, notícias on-line e rádio. Trabalhar como editora-geral e repórter na TV e no jornalismo digital me deu 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 ferramentas e fluxos de trabalho digitais, assim como guias de estilo e estratégias de comunicação para marcas digitais de notícias. Também treinei membros da equipe para usar essas ferramentas.

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

Infelizmente, os manuais e documentos que escrevi no meu emprego anterior não são públicos. Portanto, agora estou me concentrando em me envolver mais com projetos de código aberto (veja exemplos abaixo). Meu trabalho é baseado em guias de estilo, como o guia de estilo da documentação do desenvolvedor do Google e o guia de estilo da Microsoft. Uso GitHub, Slack e Linux com frequência. Escrevi documentações narrativas, além de docstrings e dicas de tipografia, usando ferramentas como Sphinx, Mypy e Sphinx autodoc.

No momento, trabalho como freelancer. Minha agenda 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 acomodar os horários e necessidades da equipe.

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

  • PyZillow: é um wrapper Python para a API do site imobiliário, Zillow.com. Além de fornecer o código e atuar como um dos mantenedores de código, criamos 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 departamentos de polícia 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.