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:
- Recurso nacional de biologia de rede (NRNB, na sigla em inglês)
- 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 (3 meses)
Project description
Com abstração
A documentação do usuário é desenvolvida para ajudar os usuários finais a usar um produto ou serviço. Uma boa documentação do usuário é muito importante porque fornece um caminho para os usuários aprenderem como usar um software, seus recursos, dicas, truques e também resolver problemas comuns encontrados ao usar o software. Isso também reduz o custo de suporte e faz parte da identidade corporativa do produto, ou seja, uma boa documentação do usuário é um sinal de que o produto é saudável e da equipe de desenvolvimento. Sem uma boa documentação do usuário, ele 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 essencial para garantir o sucesso de um produto, porque uma boa comunicação é e sempre será o centro de qualquer negócio ou produto, e uma ótima documentação apenas usa essa comunicação e a coloca em uma estrutura gerenciável que todos podem acessar para o sucesso. O SynBioHub é um repositório de design para biologia sintética. Está disponível como site público e como software de código aberto. O SynBioHub usa a Synthetic Biology Open Language (SBOL), um padrão de código aberto para representar designs genéticos, e também permite compartilhar partes do design de arquivos do GenBank e FASTA. O SynBioHub pode ser usado para publicar uma biblioteca de peças sintéticas e designs como serviço, compartilhar designs com colaboradores e armazenar projetos de sistemas biológicos localmente. Os dados no SynBioHub podem ser acessados usando a API HTTP, a API Java ou a API Python, onde podem ser integrados às ferramentas CAD para a criação de designs genéticos. O SynBioHub contém uma interface para os usuários fazerem upload de novos dados biológicos para o banco de dados, visualizar partes do DNA, realizar consultas para acessar partes desejadas e fazer o download do SBOL, GenBank, FASTA etc. Vários artigos de pesquisa e alguns tutoriais também estão disponíveis na Internet, como a seguir: 1. https://pubs.acs.org/doi/abs/abs/10.1021
Estado atual da documentação:
Atualmente, 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 e pode ajudar o usuário a navegar dentro do repositório de design. Além disso, a documentação da API também precisa ser atualizada, com alguns tópicos específicos, como solução de certos problemas peculiares que o usuário pode enfrentar. Mas a organização gravou alguns tutoriais em vídeo, como este. Realmente não há documentação escrita do usuário sobre o SynBioHub que possa orientar o usuário.
Por que a documentação do usuário proposta por você foi 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 do usuário proposta será estruturada para melhorar e garantir eficiência, consistência e tranquilidade para qualquer usuário final. Ele terá 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 discussões com o Sr. Myers , também foi decidido que a documentação da API será mesclada com a GUI e conterá seis seções da qual a 6a seção será opcional. As seções são mencionadas da seguinte maneira: 1. Introdução 2. Instruções de instalação a) A partir de uma imagem pré-criada b) Da origem c) Configuração do NGINX 3. Instruções para usuários a) Instruções detalhadas sobre como usar cada recurso da GUI b) Tutoriais para casos de uso comuns 4. Documentação da API - Endpoints - seção 5. Documentação do plug-in 6. Solução de problemas e referências futuras.
Parte 1:
Nesta seção, os usuários receberão uma introdução detalhada e vários tutoriais relacionados ao SynBioHub.
Parte 2:
Nesta seção, as diversas maneiras pelas quais o usuário pode instalar o software de código aberto usando métodos diferentes: a) usando uma imagem pré-criada b) da origem c) a configuração do NGINX
Parte 3:
Essa é a parte mais importante da documentação e que ocupará a maior parte do tempo. Aqui, cada detalhe de minuto é incluído no contexto da GUI. Como mencionado acima, vamos abordar principalmente duas questões nesta seção. Ou seja, instruções detalhadas sobre como usar cada recurso da GUI e alguns tutoriais para casos de uso comuns.
Parte 4:
Conforme mencionado acima, a barreira será usada para gerar a documentação desta parte. Nesta seção, os endpoints a seguir serão incluídos: 1. Endpoints de usuário 2. Pesquise endpoints 3. Faça o download do Endpoints 4. Faça o download do Endpoints 5. Endpoints de envio 6. Endpoints de permissão. 7. Edite o Endpoints 8. Anexar endpoints 9. Endpoints de administração
Parte 5:
Nesta seção, será incluída a documentação do plug-in, que já está presente na documentação antiga do SynBioHub. Essa seção será subdividida em duas seções: especificação e implementação do plug-in. Parte 6: [opcional] Esta seção incluirá uma lista muito comum de erros que os usuários enfrentam e algumas instruções para solução de problemas. Conforme a conversa com o Sr. Myers, foi decidido que esta seção pode ser mesclada com a seção de introdução, se isso não ficar muito longo. Análise O Sr. Myers e eu conversamos sobre como atualizar a documentação existente e também como escrever uma nova para a GUI . Nessas poucas conversas, formulamos um layout básico para a nova documentação mencionada acima, e um cronograma estimado foi fornecido na página 5 abaixo. De acordo com a discussão, vou usar o GitHub e o Markdown para criar a documentação de cada seção, exceto a Parte 4 da documentação em que a barreira será usada. Slate:- o Slate ajuda você a criar uma documentação de API elegante, inteligente e responsiva. O Slate é uma ferramenta baseada em Ruby que gera um site estático da documentação da API com três painéis e um conjunto de arquivos de markdown. Ele foi criado pelo desenvolvedor Robert Lord em 2013, quando ele estava fazendo um estágio de 18 anos na empresa de software de viagem "Tripit". Na época, ele convenceu o chefe dele a deixar o projeto em código aberto, e o resto é história. Ele tem os seguintes recursos: • Design limpo e intuitivo — Com o Slate, a descrição da sua API está no lado esquerdo da sua documentação e todos os exemplos de código estão no lado direito. Inspirado nos documentos da API da Stripe e do PayPal. A Slate é responsiva, por isso ela fica ótima em tablets, smartphones e até mesmo em impressões. • Tudo em uma única página — O tempo em que seus usuários precisavam pesquisar milhões de páginas para encontrar o que procuravam acabaram. O Slate coloca toda a documentação em uma única página. No entanto, isso não foi sacrificado. Conforme você rola a tela, o hash do navegador é atualizado para o cabeçalho mais próximo, de modo que a vinculação a um ponto específico na documentação ainda é natural e fácil. • Slate é apenas Markdown: ao escrever documentos com Slate, você está apenas escrevendo Markdown, o que facilita a edição e a compreensão. Tudo é escrito no Markdown, até mesmo os exemplos de código são apenas blocos de código Markdown. • Escreva exemplos de código em várias linguagens: se sua API tiver vinculações em várias linguagens de programação, será possível colocar guias para alternar entre elas com facilidade. Em seu documento, você distinguirá diferentes idiomas especificando o nome da linguagem na parte superior de cada bloco de código, assim como no GitHub Flavored Markdown. • Destaque de sintaxe pronta para uso em mais de 100 idiomas, sem necessidade de configuração. • Sumário automático com rolagem suave no canto esquerdo da página. Conforme você rola a tela, sua posição atual no documento é mostrada. É rápido também. Estamos usando a Slate no TripIt para criar a documentação da nossa nova API, onde nosso índice tem mais de 180 entradas. Garantimos que o desempenho continua excelente, mesmo para documentos maiores. • Permita que os usuários atualizem sua documentação: por padrão, a documentação gerada pelo Slate fica hospedada em um repositório público do GitHub. Isso não apenas significa que você recebe hospedagem sem custo financeiro para seus documentos com as páginas do GitHub, mas também simplifica para que outros desenvolvedores façam solicitações de envio para seus documentos se encontrarem erros de digitação ou outros problemas. Se não quiser usar o GitHub, você também pode hospedar seus documentos em outro lugar. • Suporte ao layout de leitura total da direita para a esquerda para idiomas RTL como árabe, persa (farsi), hebraico etc. O Verdict Slate é um dos softwares de código aberto mais eficientes para gerar a documentação e, de acordo com as discussões com meu mentor, Sr. Chris Myers, vou usar o slate para a Parte 4 e, em outras partes, o GitHub e o Markdown serão usados. Confira nas seções abaixo uma visão mais detalhada da documentação. Estrutura da documentação proposta Criei uma estrutura para o Guia do usuário do SynBioHub, que pode ser encontrada na página 2. Esta estrutura foi aceita e já foi modificada por Mr. Myers . Metas do projeto 1. Reestruturar a documentação. 2. Atualize a documentação para se adequar às versões modernas do SynBioHub. 3. Remova informações obsoletas. 4. Reescrever a documentação do usuário para facilitar o entendimento. 5. Incluir uma breve seção de pré-requisito na documentação para novos colaboradores, a fim de aumentar o entendimento básico dos conceitos biológicos básicos e da interface do SynBioHub.