Esta página foi traduzida pela API Cloud Translation.

Projeto National Resource for Network Biology (NRNB)

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:: Recurso Nacional de Biologia de Redes (NRNB)
Redator técnico:: Prubhtej_9
Nome do projeto:: Criar documentação do usuário para o SynBioHub e desenvolver tutoriais para casos de uso específicos
Duração do projeto:: Duração padrão (três meses)

Project description

Resumo

A documentação do usuário foi projetada para ajudar os usuários finais a usar um produto ou serviço. Uma boa documentação do usuário é muito importante porque oferece uma forma de os usuários aprenderem a usar um software, seus recursos, dicas, truques e também resolver problemas comuns encontrados ao usar o software. Isso também reduz o custo do suporte e faz parte da identidade corporativa do produto, ou seja, uma boa documentação do usuário é um sinal de que o produto e a equipe de desenvolvedores estão íntegros. Sem uma boa documentação do usuário, um usuário pode não saber como fazer as coisas mencionadas acima de forma eficaz e eficiente. As documentações do usuário podem desempenhar um papel crucial para garantir o sucesso de um produto porque uma boa comunicação é e sempre estará no centro de qualquer empresa ou produto, e uma ótima documentação apenas pega essa comunicação e a coloca em uma estrutura gerenciável que pode ser acessada por todos para o sucesso. O SynBioHub é um repositório de design para biologia sintética. Ele está disponível como site público e como software de código aberto. O SynBioHub usa o Synthetic Biology Open Language (SBOL), um padrão de código aberto para representar projetos genéticos, e também permite compartilhar partes de design de arquivos do GenBank e FASTA. O SynBioHub pode ser usado para publicar uma biblioteca de peças sintéticas e designs como um serviço, compartilhar designs com colaboradores e armazenar projetos de sistemas biológicos localmente. Os dados no SynBioHub podem ser acessados pela API HTTP, API Java ou API Python, onde podem ser integrados a ferramentas de CAD para a criação de designs genéticos. O SynBioHub contém uma interface para que os usuários façam upload de novos dados biológicos para o banco de dados, visualizem partes do DNA, realizem consultas para acessar as partes desejadas e façam o download de SBOL, GenBank, FASTA etc. Vários artigos de pesquisa e alguns tutoriais também estão disponíveis na Internet, como: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 O SynBioHub tem alguma documentação relacionada apenas à API, enquanto não há documentação para a GUI.

Estado atual da documentação:

No momento, a documentação do usuário está disponível em :“https://synbiohub.github.io/api-docs/#about-synbiohub”. Essa é apenas a documentação da API, e a documentação da GUI não existe, o que pode ajudar o usuário a navegar no repositório de design. Além disso, a documentação da API precisa de algumas atualizações, com alguns tópicos específicos, como a solução de problemas específicos que um usuário pode enfrentar. A organização gravou alguns vídeos tutoriais, como este. Não há documentação escrita sobre o SynBioHub que possa orientar o usuário.

Por que a documentação do usuário proposta é uma melhoria em relação à atual? Vou criar a documentação da GUI do zero usando o GitHub e o Markdown, conforme sugerido pelo mentor, Chris Myers. A documentação proposta para o usuário será estruturada para melhorar e garantir a eficiência, consistência e tranquilidade para qualquer usuário final. Ele vai conter guias escritos e imagens associadas, além de instruções e explicações sobre como usar cada recurso do simulador de código aberto SynBioHub. Durante as conversas com o Sr. Myers , também foi decidido que a documentação da API será mesclada com a GUI e conterá seis seções, das quais a sexta será opcional. As seções são mencionadas da seguinte forma: 1. Introdução 2. Instruções de instalação a) Da imagem pré-criada b) Da origem c) Configuração do NGINX 3. Instruções do usuário a) Instruções detalhadas sobre como usar cada recurso da GUI b) Tutoriais para casos de uso comuns 4. Documentação da API - Seção 5 do Endpoints. Documentação do plug-in 6. Solução de problemas e referências futuras.

Parte 1:

Nesta seção, os usuários vão receber uma introdução detalhada e vários tutoriais sobre o SynBioHub.

Parte 2:

Nesta seção, você verá as diversas maneiras de instalar o software de código aberto usando vários métodos: a) Da imagem pré-criada b) Da origem c) Configuração do NGINX

Parte 3:

Essa é a parte mais importante da documentação e vai ocupar a maior parte do tempo. Neste artigo, cada detalhe será adicionado ao contexto da GUI. Como mencionado acima, esta seção aborda principalmente duas questões: instruções detalhadas sobre como usar cada recurso da GUI e alguns tutoriais para casos de uso comuns.

Parte 4:

Como mencionado acima, a barreira será usada para gerar a documentação desta parte. Nesta seção, os seguintes endpoints serão incluídos: 1. Endpoints do usuário 2. Endpoints de pesquisa 3. Endpoints de download 4. Endpoints de download 5. Endpoints de envio 6. Endpoints de permissão. 7. Editar endpoints 8. Endpoints de anexo 9. Endpoints de administração

Parte 5:

Nesta seção, a documentação do plug-in será incluída, o que já está presente na documentação antiga do SynBioHub. Esta seção será dividida em duas partes: especificação e implementação do plug-in. Parte 6: [Opcional] Esta seção inclui uma lista muito comum de erros que os usuários enfrentam e também algumas instruções de solução de problemas. De acordo com a discussão com o Sr. Myers, decidimos que esta seção pode ser mesclada com a seção de introdução, se não ficar muito longa. Análise O Sr. Myers e eu conversamos sobre como atualizar a documentação existente e também para escrever uma nova para a GUI . Nessas poucas conversas, formulamos um layout básico para a nova documentação mencionada acima e uma estimativa de cronograma foi fornecida na página 5 abaixo. De acordo com a discussão, vou usar o github e o markdown para criar a documentação de todas as seções, exceto a Parte 4 da documentação, em que o slate será usado. Slate: a Slate ajuda você a criar uma documentação de API bonita, inteligente e responsiva. O Slate é uma ferramenta baseada em Ruby que gera um site estático de documentação de API com três painéis de ótima aparência a partir de um conjunto de arquivos Markdown. Ele foi criado pelo desenvolvedor Robert Lord em 2013, quando ele tinha 18 anos e era estagiário na empresa de software de viagens "Tripit". Ele convenceu o chefe na época a permitir que ele disponibilizasse o projeto como código aberto, e o resto é história. Ela tem os seguintes recursos: • Design limpo e intuitivo: com o Slate, a descrição da API fica no lado esquerdo da documentação, e todos os exemplos de código ficam no lado direito. Inspirado nas documentações da API da Stripe e do PayPal. O Slate é responsivo, por isso tem uma ótima aparência em tablets, smartphones e até mesmo em materiais impressos. • Tudo em uma única página: os dias em que seus usuários precisavam pesquisar milhões de páginas para encontrar o que queriam ficaram no passado. O Slate coloca toda a documentação em uma única página. No entanto, não sacrificamos a vinculação. Conforme você rola a página, o hash do navegador é atualizado para o cabeçalho mais próximo. Assim, o processo de vinculação a um ponto específico na documentação ainda é fácil e natural. • A barreira é apenas o Markdown: ao escrever documentos com o Slate, você está apenas escrevendo Markdown, o que simplifica a edição e a compreensão. Tudo é escrito em Markdown – até mesmo os exemplos de código são apenas blocos de código Markdown. • Crie exemplos de código em várias linguagens: se a API tiver vinculações em várias linguagens de programação, você poderá usar guias para alternar entre elas. No seu documento, você vai distinguir diferentes idiomas especificando o nome do idioma na parte de cima de cada bloco de código, assim como no Markdown com sabor do GitHub. • Realce de sintaxe pronto para uso em mais de 100 idiomas, sem necessidade de configuração. • Índice de rolagem automática e suave no canto esquerdo da página. À medida que você rola, ele mostra sua posição atual no documento. Ele também é rápido. Estamos usando o Slate no TripIt para criar a documentação da nossa nova API, que tem mais de 180 entradas no sumário. Garantimos que o desempenho continua excelente, mesmo para documentos maiores. • Permita que os usuários atualizem a documentação por você: por padrão, a documentação gerada pelo Slate é hospedada em um repositório público do GitHub. Isso não significa apenas que você tem hospedagem sem custo financeiro para seus documentos com as Páginas do GitHub, mas também simplifica para outros desenvolvedores fazerem solicitações de envio para seus documentos se encontrarem erros de digitação ou outros problemas. Se você não quiser usar o GitHub, também é possível hospedar seus documentos em outro lugar. • Suporte RTL: layout completo da direita para a esquerda para idiomas RTL, como árabe, persa (farsi), hebraico etc. Veredito: o Slate é um dos softwares de código aberto mais poderosos para gerar a documentação. De acordo com as discussões com meu mentor, o Sr. Chris Myers, vou usar o Slate para a Parte 4 e, para outras partes, o GitHub e o Markdown serão usados. Uma visão mais detalhada da documentação é discutida nas seções abaixo. Estrutura da documentação proposta: criei uma estrutura para o guia do usuário do SynBioHub, que pode ser encontrada na página 2. Essa estrutura foi aceita e já foi modificada pelo Sr. Myers . Metas do projeto 1. Reestruturar a documentação. 2. Atualização da documentação para se adequar às versões modernas do SynBioHub. 3. Remova informações obsoletas. 4. Reescreva a documentação do usuário para facilitar a compreensão. 5. Inclua uma breve seção de pré-requisitos na documentação para novos colaboradores para aumentar o entendimento deles sobre conceitos biológicos básicos e a interface do SynBioHub.