Projeto CERN-HSF

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:
CERN-HSF
Redator técnico:
Ariadne
Nome do projeto:
Rucio: modernize (reestruture e reescreva) a documentação da Rucio
Duração do projeto:
Duração padrão (3 meses)

Project description

Resumo: A estrutura Rucio foi desenvolvida com o objetivo de 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 adaptável, o framework é altamente escalonável, modular e extensível. Os consumidores de documentação para esse serviço seriam de origens variadas e têm requisitos variados para acessá-lo. Uma boa documentação para esse serviço deve, portanto, simplificar sua adoção e utilização para usuários finais e, ao mesmo tempo, ser uma referência para problemas comuns e solução de problemas.

Sem essa documentação, haveria obstáculos significativos na utilização eficiente e eficaz. Isso pode aumentar os custos de suporte e colocar em risco a reputação do produto. A documentação é, afinal, um modo de comunicação. Garantir que a comunicação seja encapsulada em uma estrutura gerenciável e acessível mantendo a relevância com o controle de versões apropriado é, portanto, garantir que estamos comunicando para ter sucesso.

No momento em que este artigo foi escrito, a estrutura Rucio foi utilizada para atender aos requisitos mais intensos dos experimentos ATLAS e CMS no LHC. Ela também está sendo usada para atender às necessidades de diversas comunidades científicas além do LHC, como a astrofísica. Dessa forma, é necessário que a documentação seja a mais relevante e acessível possível. Com a ajuda desse projeto, a CERN quer permitir que os usuários finais da Rucio tenham uma experiência perfeita ao usar a estrutura, fornecendo uma visão centralizada para acessar toda a documentação relevante.

Estado atual: Atualmente, a documentação do usuário está espalhada em diferentes locais e está em diversos formatos, incluindo artigos científicos, readthedocs.io com código-fonte no código, Google Drive, GitHub, DockerHub ou Wikis. Várias fontes introduzem problemas no acompanhamento de versões e na exatidã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. Especialmente no caso dos Wikis, as informações fornecidas para um experimento específico também podem ser aplicadas a outras instâncias que residem nas mesmas ou em outras fontes. No entanto, devido à falta de consolidação e de vínculos apropriados, essas informações permanecem inativas e, potencialmente, subutilizadas.

Por que a documentação do usuário proposta por você foi uma melhoria em relação à atual? Dado o problema multifacetado, o modelo proposto abaixo elimina os obstáculos com navegação, controle de versões, rastreamento e exibição de documentação, conforme detalhado abaixo:

A reestruturação da documentação visa simplificar os esforços gastos na navegação para um usuário final. Ele não precisa descer pela toca do coelho enquanto procura informações, já que essas informações seriam categorizadas/rotuladas por simplicidade. Do ponto de vista administrativo, o controle de versões e o acompanhamento seriam fáceis, já que a reestruturação daria a liberdade de categorizar com base nos requisitos. Centralizar toda a documentação reestruturada seria garantir que todas as informações ficassem visíveis para o usuário sem ter que consultar várias fontes.

Análise: Depois de ler o resumo de requisitos e conversar com a equipe de mentoria, minhas deduções quanto ao estado atual da documentação de Rucio estão abaixo:

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

  • Leia os documentos do Sphinx com código-fonte no código Link para o código: https://github.com/rucio/rucio Link para o ReadtheDocs: https://rucio.readthedocs.io/en/latest/

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

  • Link do GitHub: 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

As documentações dessas fontes estão em formatos diferentes. Por exemplo, o Google Drive tem documentação no formato Apresentações e Documentos, o GitHub tem arquivos principalmente na linguagem de marcação reStructuredText etc. A falta de controle de versões e rastreamento faz com que informações redundantes sejam publicadas em várias fontes. Não há uniformidade na rotulagem/categorização das informações. Portanto, é necessário ter experiência e conhecimento prévio ao fazer a pesquisa.

Considerando 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 familiarize com o uso delas.

Veredito: a documentação atual é desestruturada e está espalhada sem a vinculação adequada. Ele também não tem centralização e uniformidade na formatação. Por isso, os usuários precisam se esforçar mais para as pesquisas. Essas lacunas também geram uma pressão desnecessária sobre os administradores, mantenedores e leads. Por isso, é difícil manter uma abordagem de manutenção e atualização da documentação motivada pela comunidade. A experiência do usuário e do colaborador foi consideravelmente prejudicada e haveria repetição

Estrutura da documentação proposta: Após uma análise completa dos requisitos, decidi abordar as principais dificuldades usando um modelo de documentação reestruturado.
O modelo reestruturado é demonstrado no modelo anexado abaixo e categoriza todos os documentos nas sete categorias abaixo:

  • Sobre
  • Vamos começar
  • conceitos
  • Interfaces Rucio
  • Ações
  • Tutoriais
  • Conhecimento avançado

Claro, há melhorias, como a adição de links nos quais eu gostaria de trabalhar após a conclusão do programa. Com mais de 1.000 usuários ativos acessando 500 petabytes de dados no Rucio, a reestruturação proposta da documentação da empresa deve reduzir significativamente a necessidade de os usuários recorrerem à lista de e-mails de suporte. O objetivo seria melhorar a experiência do usuário com a redução do número de taxas de cliques e a fácil visualização da documentação por categorização e rotulagem. Tudo o que é necessário saber do ponto de vista da equipe de usuários/operações/administradores fica disponível em até três cliques.

Link de simulação: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

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

As bases desse sistema já estão em vigor, mas meu modelo melhoraria o sistema atual estabelecendo diretrizes adequadas para contribuição e governança com a documentação adequada. Além disso, imagino incorporar quadros de projetos do GitHub para acompanhar problemas e a integridade geral do projeto.

Cronograma: - Antes de 16 de agosto --> Conhecer as versões atuais da documentação e do Rucio --> Aprender novas técnicas e habilidades técnicas de escrita que serão úteis durante o projeto --> Contribuir com questões de documentação, se houver, relatadas no GitHub

  • Vínculo com a comunidade (17 de agosto a 13 de setembro) --> Definir um canal de comunicação e um horário para considerar a diferença de fusos horários (Pune está 3 horas e 30 minutos à frente) --> Principais dificuldades a serem identificadas para refinar os objetivos --> 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-chave da organização quanto à viabilidade e viabilidade da implementação. --> Finalização dos recursos propostos e quaisquer outras modificações que possam ser necessárias à documentação existente.

  • Período de documentação (14 de setembro a 30 de novembro) Com base no formato proposto aqui formulado, forneci um detalhamento dos principais marcos que pretendo atingir durante o período de documentação.

--> Marco 1: categorização e rotulagem ETC: 28 de setembro de 2020 Assimilar a documentação disponível e rotulá-la simplificaria muito o processo de reestruturação e remoção.

--> Marco 2: análise, remoção e reestruturação ETC: 19 de outubro de 2020 A documentação que foi categorizada durante o Marco 1 será analisada em busca de duplicatas e fontes redundantes de informações. Conforme declarado nas informações do projeto, estamos buscando uma fonte de verdade para todas as informações disponíveis.

--> Marco 3: centralização e reformatação: ETC: 9 de novembro de 2020 Depois que a documentação tiver sido removida e reestruturada corretamente, eu tentaria reformatá-la primeiro. Devido às várias fontes, os formatos são diferentes e primeiro precisam ser transformados em um formato apropriado. Depois disso, o processo de centralização fica mais fácil.

--> Marco 4: criação de painéis de acompanhamento + documentação sobre governança/contribuições ETC: 23 de novembro de 2020 Esta fase visa garantir que após a conclusão do projeto, a documentação continua atualizada. Estabelecer diretrizes e montar conselhos de projeto aliviará a pressão sobre os membros administrativos de solicitar contribuições da comunidade e monitorá-las efetivamente.

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

Por que este projeto? Eu acredito que complementar o código com uma documentação bem escrita e com controle de versões é a única maneira de permitir uma maior adoção e um melhor uso. Pessoalmente, sou fascinado pelo modo como o CERN foi pioneiro 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 por como os dados eram gerenciados para referência e uso futuro dentro da organização. Seria uma honra contribuir para a melhoria da documentação de uma estrutura que tem impulsionado algumas 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 seria a pessoa certa para este projeto, já que:

Já estou trabalhando para modificar a documentação atual do Kubernetes. Com essas contribuições, eu fui incluído como Sombra dos documentos de lançamento no ciclo de lançamento 1.19 do Kubernetes, em que contribuo para manter e fazer upgrade da documentação com eficiência para os novos recursos adicionados durante os lançamentos. Acredito que uma boa documentação é a espinha dorsal de um ótimo produto/serviço. Seja processual ou técnica, informações bem escritas, concisas e facilmente acessíveis seriam um impulso para impulsionar a adoção e ajudar no melhor uso. Por ter trabalhado com sistemas distribuídos baseados em dados ao longo de toda a minha carreira, acho que estou mais preparado para entender as complexidades dos requisitos em relação à documentação desses sistemas. Como eu mesmo sou um usuário final, conheço bem as armadilhas da documentação mal escrita/incorreta e tenho cuidado para abordá-las durante a reestruturação.