Projeto Bokeh

Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.

Resumo do projeto

Organização de código aberto:
Bokeh
Redator técnico:
vis_verborum
Nome do projeto:
Criação, leitura e compartilhamento: como otimizar a documentação do Bokeh
Duração do projeto:
Duração padrão (três meses)

Project description

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

1. Resumo

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 do PyPi) e um grande número de colaboradores (455 no GitHub). Não surpreende que a extensa documentação de Bokeh seja cultivada organicamente. E, em alguns lugares, inconsistente, difícil de acessar e complicado.

A Temporada de Documentos do Google oferece uma oportunidade única para uma revisão e revisão focadas da estrutura e do conteúdo da documentação do Bokeh e para garantir que a documentação e as ferramentas e fluxos de trabalho associados sejam preparados para o futuro.

Eu programei 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 Temporada de documentos do Google é minha experiência no jornalismo: trabalhei em redações por mais de 13 anos, muitos deles como editora-chefe e defensora da mudança digital. Além das minhas funções jornalísticas, tive responsabilidades cada vez maiores em projetar e documentar novas ferramentas digitais e guias de estilo, além de treinar a equipe da redação.

Depois de me mudar da Europa para os EUA, decidi descobrir novas maneiras de unir meu entusiasmo pela comunicação e pela programação. Achei a escrita técnica como a combinação ideal das minhas habilidades e experiências em escrita e tecnologia. Nesta proposta, vou mostrar como usar a Temporada dos Documentos do Google para otimizar a documentação do Bokeh: tornando a criação e contribuição de documentação mais convenientes, tornando a leitura da documentação mais direta e facilitando o compartilhamento de informações na documentação com outras pessoas.

2. Situação atual

A documentação oficial do Bokeh consiste nas seguintes unidades principais:

  • Documentação narrativa: guia de instalação, guia do usuário, guia para desenvolvedores, 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 extensa de notebooks Jupyter, hospedados em mybinder.org)
  • Docstrings e ajuda de modelo para ambientes de desenvolvimento integrados
  • Exemplos e README no repositório do projeto

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

A maioria das páginas da Web da documentação é 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". 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 existente foi a falta de diretrizes de estilo claras para a redação da documentação. O guia para desenvolvedores do Bokeh contém algumas instruções básicas. No entanto, este documento não contém muitas orientações sobre estilo, especialmente em relação à documentação que vai além dos docstrings. Como consequência, problemas estilísticos e estruturais dificultam o acesso às informações nos documentos, especialmente para os novatos.

Exemplo:

A página de destino da documentação do Bokeh é bastante curta e não inclui informações sobre todos os recursos disponíveis (não há menção da extensa biblioteca de docstrings e funções de ajuda de modelos, dos fóruns de suporte, das demonstrações ou do blog Medium). Isso também dificulta o início de novos usuários com o Bokeh.

3. Metas

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

3.1. Melhorar a criação de documentos

A maior parte da documentação de Bokeh é escrita por colaboradores, que a incluem como parte das 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 criação de fluxos de trabalho para criar e manter a documentação à prova do futuro: os colaboradores precisam manter um padrão de documentação consistentemente alto.

Vou garantir isso com duas abordagens:

  • Vou criar um conjunto de diretrizes de estilo simples e práticas para incluir no guia para desenvolvedores. Essas diretrizes abordam 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 vou oferecer 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 o controle de qualidade da documentação, que será adicionado aos fluxos de trabalho atuais do Bokeh para PRs (pull requests) e CI (integração contínua). Dependendo dos requisitos da equipe, isso pode significar adicionar ferramentas como pydocstyle, proselint ou sphinxcontrib-spelling (links em inglês) ao pacote de testes do Bokeh, configuração de pré-compromisso 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. Melhorar a leitura dos documentos

O objetivo de uma boa documentação é ajudar os usuários atuais e potenciais a encontrar exatamente as informações corretas e a fazer uso dessas informações da forma mais eficiente possível.

Os principais fatores de usabilidade de um texto são o estilo e a estrutura: escrever a documentação de forma clara e consistente permite que os leitores captem as informações rapidamente, sem distrações e linguagem supérflua. Uma estrutura simples e transparente da documentação facilita a localização rápida de informações relevantes.

Vou me concentrar nessas duas áreas, com ênfase na usabilidade para novos usuários. Isso inclui uma revisão completa da documentação narrativa, com foco no guia do usuário. Também vou revisar 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 na melhoria da criação de documentos descritos acima, vou me concentrar em estabelecer uma base para melhorias futuras e padrões continuamente altos para a documentação do Bokeh.

3.3. Melhorar o compartilhamento de documentos

Há cada vez mais discussões sobre o Bokeh em plataformas de terceiros. Muitas dessas plataformas usam metadados, como o OpenGraph do Facebook, para incluir prévias ricas 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 prévias de links.

Para usar essa tecnologia, vou adicionar metadados às páginas da Web geradas pelo Sphinx do Bokeh, conforme descrito no problema #9792. A maneira mais eficiente é usar uma extensão dedicada do Sphinx. Há alguns dias, a primeira versão de uma extensão Sphinx para dados do OpenGraph foi publicada no GitHub. Vou usar algumas fases da fase de desenvolvimento de documentos para ajudar a melhorar essa extensão para uso com a documentação do Bokeh.

Também criei uma prova de conceito que estou usando 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, essas informações são inseridas 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 (semelhantes às diretivas "meta" existentes do docutil). Os metadados gerados automaticamente só seriam usados como substituto, 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 do OpenGraph de alta qualidade para a documentação do Bokeh. Todo o trabalho que é feito para oferecer suporte ao OpenGraph, ao mesmo tempo, estabelece as bases para o suporte a dados estruturados.

Membros das comunidades Sphinx e ReadTheDocs demonstraram interesse em desenvolver extensões para OpenGraph e dados estruturados (nas questões #1758 e #5208, por exemplo). Vou trabalhar de perto com eles.

4. Resultados

Em resumo, estes são os resultados que espero da Temporada de documentos:

  • Diretrizes de estilo de documentação para colaboradores do Bokeh
  • Fluxos de trabalho de PR e CI revisados para incluir o controle de qualidade de documentação automatizado
  • 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 uma extensão do Sphinx funcional

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

5. Cronograma

Antes da fase de formação de vínculo com a comunidade: já estou participando ativamente de várias discussões no repositório GitHub do Bokeh e já entrei em contato com Bryan Van de Ven e Pavithra Eswaramoorthy, mentores de Bokeh para a Temporada de Documentos do Google. Permanecerei ativo na conversa sobre o Bokeh e também me familiarizarei ainda mais com ele, criando e publicando visualizações.

Fase de vinculação à comunidade (17/08 a 13/09):

  • Conheça a equipe principal e refine o plano do projeto em troca com mentores
  • Definir uma programação e canais de comunicação para relatórios e feedbacks regulares com os mentores
  • Ser ativo no Slack do Bokeh para informar todos os colaboradores interessados sobre a Temporada de documentos do Google e as metas da fase de desenvolvimento de documentos
  • Coletar feedback dos colaboradores do Bokeh para refinar ainda mais o plano para a fase de desenvolvimento do documento

Fase de desenvolvimento da documentação

Semana 1, 14/09 a 20/09:

  • Começar a auditoria e edição da documentação narrativa
  • Começar a elaborar as diretrizes de estilo

Semana 2, de 21/09 a 27/09:

  • Continuar trabalhando 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, de 28/09 a 10/04:

  • Concluir as diretrizes de estilo
  • Página de destino da finalização da documentação

Semana 4, 5 a 11 de outubro:

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

Semana 5, de 12 a 18 de outubro:

  • Organize uma sessão de perguntas e respostas com os colaboradores do 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 atual para metadados do OpenGraph em uma extensão implantável do Sphinx
  • Revisar as diretrizes de estilo com base no feedback da sessão de perguntas e respostas com os colaboradores do Bokeh

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

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

Semana 7, de 26/10 a 1/11:

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

Semana 8, 2 a 8 de novembro:

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

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

  • Implantar ferramentas de controle de qualidade de documentos em fluxos de trabalho de RP e CI
  • Atualize e publique o guia do desenvolvedor para incluir diretrizes de estilo e inclusões ao fluxo de trabalho de RP e CI

Semana 10, de 16/11 a 22/11:

  • Finalizar as tarefas restantes

Semana 11, de 23 a 29 de novembro:

  • 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, 03/12 a 10/12:

  • Finalizar e enviar a avaliação do projeto

Após a conclusão da temporada de documentos do Google:

  • Espero me envolver 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 ferramenta no jornalismo de dados. Por exemplo, escrever sobre o Bokeh com um público jornalístico em mente ou oferecer palestras sobre o uso do Bokeh em contextos jornalísticos.

6. Sobre mim

Sou jornalista, com experiência em notícias para TV, on-line e rádio. Trabalhar como editor-chefe e repórter de notícias de TV e digitais me deu anos de experiência em redação e edição. Ao mesmo tempo, trabalhei em vários projetos de transformação digital e automação. Escrevi vários manuais sobre ferramentas e fluxos de trabalho 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 pela interseção entre comunicação e tecnologia. Um mundo totalmente novo se abriu para mim quando aprendi a programar em Python: consegui fazer análises e visualizações de dados para 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 de redação.

Os manuais e documentos que escrevi em meu último emprego, infelizmente, não são públicos. Por isso, agora estou me concentrando em me envolver mais com projetos de código aberto (confira exemplos abaixo). Baseei meu trabalho de redação técnica em guias de estilo, como o guia de estilo de documentação para desenvolvedores do Google e o guia de estilo da Microsoft. Uso regularmente o GitHub, o Slack e o Linux. Tenho escrito documentações narrativas, bem como docstrings e dicas de tipo, usando ferramentas como Sphinx, Mypy e Sphinx autodoc.

Atualmente, trabalho como freelancer. Minha agenda oferece a flexibilidade necessária para trabalhar na documentação do Bokeh por cerca de 25 horas por semana durante a fase de desenvolvimento da documentação. Trabalho no fuso horário do Pacífico, mas fico feliz em atender aos horários e às necessidades da equipe.

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

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

  • PyPresseportal: o PyPresseportal é um wrapper 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 Python para acessar os extensos recursos de dados do site como objetos Python. Escrevi o código e toda a documentação baseada no Sphinx.