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:
- Creative Commons
- Redator técnico:
- nimishnb (link em inglês)
- Nome do projeto:
- Guia de uso do vocabulário
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Sinopse do projeto
O vocabulário tem um imenso potencial para ser usado como uma biblioteca principal de componentes de interface do usuário para a criação de sites. Ele precisa de um guia de instruções robusto, mas acessível para leigos. Informações importantes para desenvolvedores, como guias de componentes, especificações de uso e ajustes na configuração, são parte essencial de qualquer documentação. Isso não apenas incentivará os usuários existentes a ter uma ideia de como o vocabulário continua a crescer e atingir novos marcos, mas também promoverá o uso do Vocabulário em projetos comparativamente mais novos. Os resultados desejados da minha experiência como estagiário envolveriam não apenas a criação de um guia simples para usar os componentes pré-existentes, mas também o design e o desenvolvimento de uma página inicial (levando a uma documentação integrada para cada um) para Vocabulário, Vocabulário e Fontes.
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 que os desenvolvedores consideram ao escolher um conjunto de tecnologias adequado para criar os aplicativos é: "A biblioteca está bem documentada? Ela é bem mantida? Ele oferece suporte a uso e erros consideráveis?". Essas são exatamente as perguntas que devemos nos fazer ao desenvolver essa ideia de projeto. Da perspectiva da engenharia de software:
Análise de requisitos:há uma necessidade imanente de 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 negligente. Os links para essas documentações devem ser uma página inicial atrativa, que capture o interesse das pessoas em um instante. A documentação deve ser bem organizada, permitindo um fluxo contínuo por ela.
Especificações:dependendo dos requisitos, as especificações podem ser definidas. O conteúdo da documentação pode ser formado a partir dos dados presentes nos sites do CC netlify, junto com algumas inspirações de documentações conhecidas, como semantic-ui, scikit-learn, numpy, bootstrap etc. O resultado dessa tarefa seria a página de destino necessária e os guias de documentação completos.
Alguns problemas gerais relacionados a Vocabulário, Vocabulário, Vocabulário e Fontes atualmente:
Não há documentação e, mesmo que haja alguma, partes dela estão espalhadas pelos sites da 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, é preciso alguns cliques adicionais. Uma simples pesquisa no Google por algo como “Componente de guias CC Vocabulário” não retorna a informação desejada. Uma opção de pesquisa nos guias de documentação melhoraria muito a UX.
Uma descrição textual um pouco mais detalhada dos componentes, com detalhes não óbvios.
Sem opção de execução ao vivo. Uma execução ao vivo é suportada por diversos sites, como o JSFiddle, que permite que os desenvolvedores tenham uma ideia do componente sem executar um aplicativo inteiro para vê-lo funcionar.
A solução
Há várias soluções possíveis. No entanto, vou abordar alguns aqui e apresentar minha solução final na parte de conclusão:
= Usar readthedocs readthedocs é uma solução bem conhecida para escrever documentação para bibliotecas de código aberto. Ele é baseado no Sphinx, a ferramenta de documentação do Python.
Vantagens:
- Forma amplamente aceita de geração de documentação, usada por organizações como a Ethereum (Solidity).
- Documentação idealmente estruturada.
- Hospedagem estática sem custo financeiro.
Desvantagens:
- Falta de controle absoluto sobre o estilo.
= Uso do Sphinx Podemos também usar o sphinx de forma nativa na documentação. Ele fornece bons recursos para todos os nossos propósitos.
Vantagens:
- A ferramenta Python mais popular para documentação.
- Também é compatível com pesquisas de documentação.
- O CSS padrão pode ser substituído por um personalizado, com algum controle sobre HTML usando arquivos .rst.
Desvantagens:
- Envolvia programação em Python e em formato de texto reestruturado (.rst), o que será um desvio das linguagens sugeridas do projeto.
Como usar temas do Jekyll Os temas do Jekyll são integrados às páginas do GitHub, e há modelos pré-existentes que podem ser personalizados de acordo com nossas necessidades.
Vantagens:
- Temas de documentação prontos para todas as finalidades.
- O CSS e os estilos padrão podem ser substituídos pelos personalizados e ter controle sobre HTML também.
- Extrai o CSS padrão do Primer para criar as páginas.
- Fácil integração com páginas do GitHub.
Desvantagens:
- talvez não ofereçam a melhor estruturação de documentação.
Como usar 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 o layout, as cores e os estilos.
- Fácil uso de componentes de vocabulário.
- Incorporação fácil de snippets de código e links executados em tempo real.
Desvantagens:
- Pode ser uma abordagem mais demorada.
= Como usar o Haroopad Isso proporciona uma solução alternativa de marcação.
Vantagens:
- Isso envolveria um mínimo de programação trabalhosa.
- 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.
- Pode não ser compatível com MDX.
= Como usar o MKDocs Isso proporciona outra solução de marcação alternativa.
Vantagens:
- Isso envolveria um mínimo de codificação trabalhosa (novamente).
- Escreva mais com uma abordagem com menos código.
Desvantagens:
- Falta de controle sobre o CSS.
- podem não ter o melhor suporte da comunidade;
- Usa Python. Pode haver ainda mais a necessidade de ativar uma instância do Amazon S3.
= Como usar VueJS +StorybookJS Esta abordagem é comumente usada em Vocabulário e repositórios associados.
Vantagens:
- Usar tecnologias com garantia de funcionamento, de acordo com as experiências profissionais anteriores.
- Familiaridade com a base de código.
- Não há tecnologia competente neste espaço.
Desvantagens:
- Opções mais simples também podem estar presentes para os mesmos fins.
Em conclusão, gostaria de pensar que a abordagem envolvendo VueJS+Storybook (HTML,CSS,JS) parece a mais adequada, já que também estou confortável com ela. No entanto, isso também significa que não vamos trabalhar por completo no desenvolvimento desse aplicativo. Também seria bastante simples usar componentes de vocabulário CC. No entanto, para decidir a estrutura da documentação, é preciso considerar como o conteúdo é dividido entre subtítulos na documentação readthedocs. Fiquei impressionado com o site de IU semântica, que usa o StoryBook, porque ele tem uma aparência minimalista e é fácil saber o que querem com apenas alguns cliques. Além da interface semântica, também analisei o Material Design, Primer, Bootstrap, Carbon Design etc. para serem usados como guias de estilo de interface e sistemas de design no meu trabalho. Também podemos pesquisar temas de documentação de Jekyll prontos para isso.