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:
- Creative Commons
- Redator técnico:
- nimishnb
- Nome do projeto:
- Guia de uso de vocabulário
- Duração do projeto:
- Duração padrão (três meses)
Project description
Sinopse do projeto
O Vocabulary tem um imenso potencial para ser usado como uma biblioteca de componentes de interface principal para criação de sites. O que ele precisa é de um guia de instruções robusto, mas fácil de entender. Informações importantes para os desenvolvedores, como guias de componentes, especificações de uso e ajustes de configuração, são uma parte essencial de qualquer documentação. Isso não apenas incentiva os usuários atuais a entender como o vocabulário continua crescendo e alcançando novos marcos, mas também promove o uso do Vocabulary em projetos mais recentes. Os resultados esperados do meu período como estagiário não envolveriam apenas escrever um guia prático para usar os componentes pré-existentes, mas também projetar e desenvolver uma página inicial (que leva a uma documentação integrada para cada um) para Vocabulary, Vue-Vocabulary e Fonts.
plano do projeto
O problema:a documentação é um dos principais motivos que determinam o sucesso de uma determinada biblioteca de código aberto. A principal pergunta dos desenvolvedores ao escolher um conjunto de tecnologias adequado para criar aplicativos é "A biblioteca está bem documentada? Ele é bem mantido? Ele tem suporte considerável para uso e erros?". Essas são exatamente as perguntas que devemos fazer ao desenvolver essa ideia de projeto. Do ponto de vista da engenharia de software:
Análise de requisitos:é necessário ter uma documentação concisa e consolidada para nossas necessidades. A falta de documentação prejudica as perspectivas futuras dos aplicativos de código aberto e é, de longe, um componente essencial e não desprezível. O link para esses documentos precisa ser uma página inicial atraente, que capture o interesse das pessoas em um instante. A documentação precisa estar bem organizada, permitindo um fluxo contínuo.
Especificações:dependendo dos requisitos, as especificações podem ser definidas. O conteúdo da documentação pode ser formado a partir de dados presentes nos sites da CC netlify, com alguma inspiração de documentações conhecidas, como semantic-ui, scikit-learn, numpy, bootstrap etc. O resultado dessa tarefa será a página de destino necessária e os guias de documentação completos.
Alguns problemas gerais relacionados ao Vocabulary, Vue-Vocabulary e Fonts:
Falta de documentação e, mesmo que haja alguma, partes dela estão espalhadas por todos os sites do Netlify. Isso não permite que usuários, desenvolvedores ou colaboradores externos usem nossa biblioteca.
Para chegar a um determinado componente e copiar o código correspondente, são necessários cliques adicionais. Uma pesquisa simples no Google por algo como "Vocabulário de CC do componente de guias" não retorna as informações desejadas. Uma opção de pesquisa nos guias de documentação melhoraria muito a UX.
Uma descrição um pouco mais detalhada dos componentes, descrevendo os detalhes não óbvios.
Não há opção de transmissão ao vivo. Vários sites, como o JSFiddle, oferecem suporte a uma execução em tempo real, que permite que os desenvolvedores tenham uma ideia do componente sem executar um aplicativo inteiro para conferir se ele funciona.
A solução
Há várias soluções possíveis. No entanto, vou abordar algumas delas aqui e apresentar minha solução final na parte de conclusão:
= Como usar o readthedocs O readthedocs é uma solução conhecida para escrever documentação de bibliotecas de código aberto. Ele é baseado na Sphinx, a ferramenta de documentação Python.
Vantagens:
- Forma amplamente aceita de geração de documentação, usada por organizações como a Ethereum (Solidity).
- Documentação estruturada de maneira ideal.
- Hospedagem estática sem custo financeiro.
Desvantagens:
- Falta de controle absoluto sobre o estilo.
= Como usar o Sphinx Também poderíamos usar nativamente o Sphinx para a parte da documentação, porque ele oferece bons recursos para todos os nossos objetivos.
Vantagens:
- A ferramenta de Python mais conhecida para documentação.
- Também oferece suporte a pesquisas de documentação.
- O CSS padrão pode ser substituído por um personalizado; parte do controle sobre o HTML usando arquivos .rst.
Desvantagens:
- Envolve programação em Python e formato de texto reestruturado (.rst), que é um desvio das linguagens de projeto sugeridas.
= Usando temas do Jekyll Os temas do Jekyll são integrados às páginas do GitHub, e há modelos predefinidos que podem ser personalizados de acordo com nossas necessidades.
Vantagens:
- Temas de documentação prontos para todos os fins.
- O CSS e os estilos padrão podem ser substituídos por personalizados, controlando também o HTML.
- Extrai o CSS padrão do Primer para criar as páginas.
- Integração fácil com as páginas do GitHub.
Desvantagens:
- Não oferece a melhor estrutura de documentação.
=Usar as páginas do GitHub As páginas padrão do GitHub para criar nosso site estático (HTML, CSS, JS).
Vantagens:
- Controle total sobre quase tudo em questão.
- Flexibilidade máxima para decidir layout, cores e estilos.
- Uso fácil dos componentes do Vocabulary.
- Incorporação fácil de snippets de código e links de execução ao vivo.
Desvantagens:
- Pode ser uma abordagem mais demorada.
= Usando o Haroopad Isso oferece uma solução alternativa de markdown.
Vantagens:
- Isso envolveria um mínimo de codificação complicada.
- O foco seria escrever as documentações perfeitamente.
Desvantagens:
- Falta de controle sobre o CSS.
- Pode ou não ter o melhor suporte da comunidade.
- Talvez não ofereça suporte ao MDX.
= Usando o MKDocs Isso oferece outra solução alternativa de Markdown.
Vantagens:
- Envolve programação mínima (de novo).
- Escreva mais, use menos código.
Desvantagens:
- Falta de controle sobre o CSS.
- Talvez não tenha o melhor suporte da comunidade.
- Usa Python. Pode ser necessário criar uma instância do Amazon S3.
= Usando VueJS +StorybookJS Essa abordagem é comumente usada no Vocabulary e nos repositórios relacionados.
Vantagens:
- Usar tecnologias que funcionam bem, considerando experiências profissionais anteriores.
- Conhecer a base do código.
- Não há tecnologia competente neste espaço.
Desvantagens:
- Opções mais simples também podem ser usadas para os mesmos fins.
Em conclusão, a abordagem que envolve o VueJS+Storybook (HTML,CSS,JS) parece ser a mais adequada, já que eu também me sinto confortável com ela. No entanto, isso também significa que não vamos nos esforçar muito para desenvolver esse aplicativo. Também seria bastante simples usar os componentes de vocabulário CC. No entanto, para decidir a estrutura da documentação, é preciso considerar a forma como o conteúdo é dividido entre os subtítulos na documentação do readthedocs. Fiquei impressionado com o site de interface semântica (que usa o StoryBook), porque ele tem um visual minimalista e é fácil descobrir o que eles querem com apenas alguns cliques. Além do Semantic-UI, também dei uma olhada no Material Design, no Primer, no Bootstrap, no Carbon Design etc. para serem usados como guias de estilo de IU e sistemas de design para meu trabalho. Também podemos procurar temas de documentação prontos do Jekyll para nos inspirarmos.