Projeto CERN-HSF

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:
CERN-HSF
Redator técnico:
Ariadne
Nome do projeto:
Rucio: modernizar (reestruturar e reescrever) a documentação do Rucio
Duração do projeto:
Duração padrão (três meses)

Project description

Resumo: O framework Rucio foi desenvolvido para gerenciar e organizar grandes volumes de dados científicos distribuídos geograficamente em data centers heterogêneos. Com recursos como recuperação de dados distribuídos e replicação adaptativa, o framework é altamente escalonável, modular e extensível. Os consumidores da documentação de um serviço como esse têm origens e requisitos variados ao acessá-la. Uma boa documentação para esse serviço deve simplificar a adoção e a utilização para os usuários finais, além de ser uma referência para problemas comuns e solução de problemas.

Na ausência dessa documentação, haveria obstáculos significativos na utilização eficiente e eficaz. Isso pode aumentar os custos de suporte e prejudicar a reputação da identidade corporativa do produto. Afinal, a documentação é um modo de comunicação. Garantir que a comunicação seja encapsulada em uma estrutura gerenciável e acessível e que se mantenha relevante com o controle de versões adequado é, portanto, garantir que estamos nos comunicando para o sucesso.

No momento em que este artigo foi escrito, o framework Rucio foi usado para atender aos requisitos de alta energia dos experimentos ATLAS e CMS no LHC. Ele também está sendo usado para atender às necessidades de diversas comunidades científicas além do LHC, como a astrofísica. Por isso, é necessário que a documentação seja o mais relevante e acessível possível. Com a ajuda desse projeto, o CERN quer permitir que os usuários finais da Rucio tenham uma experiência integrada ao utilizar o framework, oferecendo uma visualização centralizada para acessar toda a documentação relevante.

Estado atual: Atualmente, a documentação do usuário está espalhada em diferentes lugares e em vários formatos, incluindo artigos científicos, readthedocs.io com origem no código, Google Drive, GitHub, DockerHub ou Wikis. Várias fontes apresentam problemas com o rastreamento de versões e a correção da documentação. Além disso, um modelo descentralizado de documentação apresenta obstáculos significativos na navegação e na exibição de informações relevantes para um determinado caso de uso. No caso das wikis, as informações fornecidas para um experimento específico podem ser aplicáveis a outras instâncias nas mesmas/outras fontes. No entanto, devido à falta de consolidação e vinculações adequadas, essas informações estão inativas e, potencialmente, subutilizadas.

Por que a documentação do usuário proposta é uma melhoria em relação à atual? Devido ao problema multidimensional, o modelo proposto abaixo elimina os obstáculos de navegação, versionamento, rastreamento e exibição da documentação, conforme detalhado abaixo:

A reestruturação da documentação visa simplificar os esforços de navegação para um usuário final. Ele/ela não precisa se aprofundar na busca por informações, já que elas são categorizadas/rotuladas para simplificar. Do ponto de vista administrativo, a versão e o acompanhamento seriam facilitados, já que a reestruturação ofereceria a liberdade de categorizar com base no requisito. Centralizar toda a documentação reestruturada seria garantir que todas as informações estejam visíveis para o usuário sem precisar consultar várias fontes.

Análise: depois de ler o resumo de requisitos e conversar com a equipe de mentoria, minhas deduções do estado atual da documentação da Rucio são as seguintes:

Há seis principais fontes de documentação: - Link do Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Readthedocs com o Sphinx como fonte no código Link para o código: https://github.com/rucio/rucio Link para o ReadtheDocs: https://rucio.readthedocs.io/pt-br/latest/

  • DockerHub Link: https://hub.docker.com/u/rucio

  • GitHub Link: https://github.com/rucio/rucio

  • Wikis Link: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing

  • Artigos científicos Link: https://arxiv.org/abs/1902.09857

A documentação dessas fontes está em formatos diferentes. Por exemplo, o Google Drive tem documentação na forma de slides e documentos, o GitHub tem arquivos principalmente na linguagem de marcação reStructuredText etc. Não há controle de versão e rastreamento, o que leva à publicação de informações redundantes em várias fontes. Não há uniformidade na rotulação/categorização das informações. Portanto, é necessário ter experiência e conhecimento anteriores durante a pesquisa.

Dada a infinidade de formatos e fontes, a expectativa é reestruturar e centralizar as informações usando o mkdocs. Para entender melhor as ferramentas, pesquisei e me familiarizei com o uso delas.

Veredicto: a documentação atual está desestruturada e espalhada sem vinculação adequada. Também falta centralização e uniformidade na formatação. Isso faz com que os usuários tenham que se esforçar mais para fazer pesquisas. Essas lacunas também causam pressão desnecessária nos administradores/mantenedores/líderes, o que dificulta a manutenção de uma abordagem orientada pela comunidade para manutenção e atualização da documentação. A experiência do usuário e do colaborador é consideravelmente degradada e seria repetida

Estrutura da documentação proposta: Depois de uma análise detalhada dos requisitos, decidi abordar os principais problemas com um modelo reestruturado de documentação.
O modelo reestruturado é demonstrado no modelo anexado abaixo e categoriza cada parte da documentação nas sete categorias abaixo:

  • Sobre
  • Primeiros passos
  • Conceitos
  • Interfaces do Rucio
  • Tarefas
  • Tutoriais
  • Conhecimento avançado

É claro que há melhorias, como adicionar links, que gostaria de trabalhar após a conclusão deste programa. Com mais de 1.000 usuários ativos acessando 500 petabytes de dados no Rucio, a reestruturação proposta da documentação deve reduzir significativamente a necessidade de os usuários recorrerem à lista de discussão de suporte. O objetivo é melhorar a experiência do usuário reduzindo o número de taxas de cliques e facilitando a visualização da documentação por meio de categorização e rotulagem. Tudo o que há para saber da perspectiva de um usuário/operações/pessoal administrativo estaria disponível em três cliques ou menos.

Link do modelo: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Objetivos do projeto: - Analisar e remover informações redundantes disponíveis de várias fontes. Ou seja, cada informação precisa ter uma fonte de verdade. - Reestruturar, rotular e categorizar a documentação existente em diferentes partes - Migrar a documentação reestruturada para uma visualização centralizada baseada no mkdocs - Reformatar/importar a documentação que não pode ser migrada devido a restrições de formato de arquivo - Configurar a modificação da documentação orientada pela comunidade para garantir que todas as lacunas sejam preenchidas, em termos de vinculações, atualizações de informações ou correção de erros.

Os princípios básicos desse sistema já existem. No entanto, meu modelo melhoraria o sistema existente estabelecendo diretrizes adequadas para contribuição e governança com a documentação apropriada. Além disso, imagino incorporar as project boards do GitHub para acompanhar problemas e a integridade geral do projeto.

Cronograma: - Antes de 16 de agosto --> Familiarizar-se com as versões atuais da documentação e do Rucio --> Aprender novas técnicas e habilidades de redação técnica que serão úteis durante o período do projeto --> Contribuir para problemas de documentação, se houver, informados no GitHub

  • Fortalecimento da comunidade (17 de agosto a 13 de setembro) --> Configure um canal de comunicação e um horário para considerar a diferença de fuso horário (Pune está 3 horas e 30 minutos à frente) --> Pontos principais a serem identificados para refinar as metas --> Participe de conversas para saber mais sobre a comunidade, a organização e a estrutura. --> Avaliação da estrutura de documentação proposta com mentores e outros membros importantes da organização para viabilidade e viabilidade da implementação. --> Finalização dos recursos propostos e de quaisquer outras modificações que precisem ser feitas na documentação atual.

  • Período de documentação (14 de setembro a 30 de novembro) Com base no formato proposto que formei aqui, forneci uma divisão dos principais marcos que pretendo alcançar durante o período de documentação.

--> Etapa 1: categorização e rotulagem ETC: 28 de setembro de 2020 Assimilar a documentação disponível e rotular as informações simplifica muito o processo de reestruturação e poda.

--> Etapa 2: análise, poda e reestruturação ETC: 19 de outubro de 2020 A documentação categorizada na etapa 1 será analisada para identificar duplicações e fontes redundantes de informações. Conforme declarado nas informações do projeto, nosso objetivo é ter uma única fonte de verdade para todas as informações disponíveis.

--> Etapa 3: centralização e reforma da documentação: ETC: 9 de novembro de 2020 Depois que a documentação for podada e reestruturada corretamente, a primeira etapa será reformulá-la. Devido às várias fontes, os formatos são diferentes e precisam ser transformados em um formato adequado. Depois disso, o processo de centralização fica mais fácil.

--> Etapa 4: configurar painéis de acompanhamento e documentação sobre governança/contribuições ETC: 23 de novembro de 2020 Esta fase é para garantir que, após a conclusão do projeto, a documentação continue atualizada. Estabelecer diretrizes e configurar painéis de projetos vai facilitar o trabalho dos membros administrativos para solicitar contribuições da comunidade e acompanhar de forma eficaz.

--> Avaliação de projeto (30 de novembro a 5 de dezembro) Enviar um relatório de projeto e uma avaliação dos meus mentores Escrever e enviar um relatório sobre minha experiência como participante da Temporada de documentos.

Por que este projeto? Acredito que complementar o código com documentação bem escrita e com versões é a única maneira de permitir mais adoção e melhor uso. Pessoalmente, fiquei fascinado pela forma como a CERN é pioneira em pesquisas de ponta em diferentes áreas da física. Dada a escala de informações processadas, transferidas e geradas durante esses experimentos, sempre me interessei em saber como os dados eram gerenciados para referência e uso futuro na organização. Seria uma honra contribuir para a melhoria da documentação de um framework que tem impulsionado pesquisas e descobertas científicas incríveis.

Por que sou a pessoa certa para este projeto? Além de atender aos pré-requisitos, tenho certeza de que sou a pessoa certa para este projeto porque:

Já estou trabalhando na modificação da documentação atual do Kubernetes. Essas contribuições resultaram na minha inscrição como um Release Docs Shadow para o ciclo de lançamento 1.19 do Kubernetes, em que contribuo para manter e atualizar a documentação de novos recursos adicionados durante os lançamentos. Acredito que uma boa documentação é a base de um ótimo produto/serviço. Seja processual ou técnica, informações bem escritas, concisas e de fácil acesso seriam um impulso para impulsionar a adoção e ajudar no melhor uso. Como trabalhei com sistemas distribuídos orientados a dados durante toda a minha carreira, acredito que tenho a melhor posição para entender as complexidades dos requisitos em relação à documentação desses sistemas. Como já fui usuário final, conheço as armadilhas da documentação mal escrita/incorreta e tenho cuidado para considerá-las durante a reestruturação.