Esta página contém os detalhes de um projeto de escrita técnica aceito para o Temporada dos Documentos Google.
Resumo do projeto
- Organização de código aberto:
- VideoLAN
- Redator técnico:
- Edidiong Anny Asikpo
- Nome do projeto:
- Modernizar (reescrever) a documentação do usuário do VLC
- Duração do projeto:
- Duração padrão (três meses)
Project description
ABSTRATA
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 de suporte e faz parte da identidade corporativa do produto: uma boa documentação do usuário é um sinal de saúde do produto e da equipe de desenvolvimento.
Sem uma boa documentação do usuário, ele pode não saber como fazer as coisas acima de maneira eficaz e eficiente. A documentação do usuário pode ter um papel fundamental na garantia do sucesso de um produto, porque uma boa comunicação é e sempre será o centro de qualquer empresa ou produto. Uma boa documentação apenas leva essa comunicação para um framework gerenciável que todos podem acessar para ter sucesso.
No momento em que este artigo foi escrito, a documentação do usuário do VLC foi acessada 4.634.065 vezes, e o download do player de mídia do VLC era de aproximadamente 23 milhões de vezes por mês no site principal. Isso mostra que muitas pessoas em todo o mundo usam o VLC Media Player e podem querer ler a documentação do usuário para obter orientações sobre como usar o player de mídia. No entanto, a documentação do usuário do player de mídia do VLC está atualmente desatualizada e incompleta (foi modificada pela última vez em 28 de outubro de 2015). A comunidade do VideoLAN quer usar esse projeto para melhorar a documentação do usuário e permitir que os usuários finais tenham uma experiência perfeita ao usar o player de mídia VLC.
ESTADO ATUAL
No momento, a documentação do usuário está disponível em uma página da wiki. Ele é obsoleto, incompleto, difícil de navegar ou encontrar informações, não inclui informações sobre a versão atual do player de mídia e só pode ser traduzido em alemão, o que causa um grande contratempo para pessoas que não sabem ler em inglês.
POR QUE A DOCUMENTAÇÃO DE USUÁRIO PROPOSTA É UMA MELHORIA EM RELAÇÃO À ATUAL?
A documentação do usuário proposta será estruturada para melhorar e garantir eficiência, consistência e tranquilidade para o usuário final. Ele vai conter guias escritos e imagens associadas, instruções e explicações sobre como usar cada recurso do VLC Media Player, atualizado, fácil de navegar, compreensível e traduzível em pelo menos cinco idiomas principais.
Mentores: Jean-Baptiste, Alex e Simon
ANÁLISE
Jean-Baptiste e eu conversamos sobre o novo ambiente para o qual a documentação do usuário atual seria migrada para melhorias. Ele compartilhou dois links que mostravam um repositório Gitlab do arquivo de origem escrito com o Sphinx e a documentação principal hospedada em Read the Docs. Ele disse que eles esperam que a nova documentação seja semelhante a ela. Pesquisei bastante sobre essas ferramentas para entender melhor como elas funcionam.
Esfinge
O Sphinx é uma solução robusta e madura para documentação de software. Ele inclui vários recursos esperados pelos autores, como publicação de origem única, reutilização de conteúdo por meio de inclusões, inclusões condicionais com base no tipo de conteúdo e nas tags, vários temas HTML avançados que oferecem uma ótima experiência do usuário em dispositivos móveis e computadores, referências em páginas, documentos e projetos, suporte a índice e glossário e internacionalização. Ele também usa o reStructuredText como linguagem de marcação, e muitos dos pontos fortes dele vêm do poder e da simplicidade do reStructuredText e da capacidade de traduzir a documentação.
Read the Docs
O Read the Docs simplifica a documentação de software automatizando a criação, a versão e a hospedagem dos seus documentos. Ela nunca fica fora de sincronia. Ou seja, sempre que você envia um código para seu sistema de controle de versão favorito, seja Git, Mercurial, Bazaar ou Subversion, o Read the Docs cria automaticamente os documentos para que seu código e a documentação estejam sempre atualizados. Ele tem várias versões. O Read the Docs pode hospedar e criar várias versões dos seus documentos. Portanto, ter uma versão 1.0 e uma versão 2.0 é tão fácil quanto ter uma ramificação ou tag separada no seu sistema de controle de versões. O Read the Docs é sem custo financeiro e de código aberto e hospeda a documentação de quase 100.000 projetos de código aberto, grandes e pequenos, em quase todas as linguagens humanas e de computador.
VEREDITO
O Sphinx é uma ferramenta incrivelmente poderosa, e o Read the Docs é baseado nela para hospedar a documentação do Sphinx e manter seus documentos atualizados em todas as versões. Juntos, eles são um conjunto maravilhoso de ferramentas que desenvolvedores e redatores técnicos podem usar para criar a melhor documentação de usuário.
O Sphinx inclui suporte para a tradução da documentação para vários idiomas. Ele oferece suporte ao controle de versões, que será usado para gerenciar a documentação. Ao contrário do wiki atual, em que qualquer pessoa pode editar e não adicionar as informações corretas, esse sistema de controle de versão garante que todas as mudanças sejam analisadas antes de serem mescladas ao repositório principal. O controle de versão também vai aumentar a contribuição de código aberto para o projeto, porque as pessoas podem criar problemas, abrir solicitações de pull, etc. O Sphinx e o Read the Docs são usados por uma lista de outras comunidades, como ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs etc., e é uma ótima ferramenta para a nova documentação do usuário do VLC.
Não apenas li sobre essas ferramentas, mas também criei um exemplo básico. Este é o link para meu repositório Gitlab: https://gitlab.com/Didicodes/demo-vlc-user-documentation. A versão hospedada em readthedocs pode ser encontrada aqui: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/).
ESTRUTURA DA DOCUMENTAÇÃO PROPOSTA
Criei uma estrutura para a documentação do usuário do VLC, que pode ser encontrada aqui: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Antes do início da implementação da nova estrutura, ela precisa ser aprovada pelos mentores. Isso significa que é provável que a estrutura mude após a revisão dos mentores.
METAS DO PROJETO
- Reestruturar a documentação.
- Atualizar a documentação para se adequar às versões modernas do VLC.
- Migre a documentação do usuário para o Gitlab usando Sphinx e ReadtheDocs.
- Remova imagens e informações obsoletas.
- Reescreva a documentação do usuário para facilitar a compreensão.
- Configure-o para tradução usando a internacionalização Sphinx.
- Promova a comunidade de documentação para que os usuários possam relatar ou resolver quaisquer problemas encontrados durante a leitura da documentação.
POR QUE ESSE PROJETO?
Sempre tive a convicção de que escrever códigos, resolver problemas e criar softwares atinge todo o potencial quando você também tem a capacidade de ensinar as pessoas por escrito. Pessoalmente, sempre me fascinei com os esforços da comunidade VideoLAN para criar soluções de software sem custo financeiro para multimídia. Quando criança, eu sempre usava o VLC Media Player para ouvir música ou assistir filmes porque ele era muito alto e tinha muitos recursos. Será uma honra trabalhar com a comunidade que contribuiu para tornar minha infância incrível.
POR QUE SOU A PESSOA CERTA PARA ESTE PROJETO
Acredito que sou a pessoa certa para este projeto porque:
- Tenho experiência anterior na melhoria da documentação de organizações e posso usar qualquer sistema de controle de versões, portanto, executar comandos no Gitab não será um problema. Além disso, o que me motiva é trabalhar em projetos que geram valor para as pessoas.
- Eu acredito que se você quer que alguém faça algo da maneira mais eficiente possível, você documenta isso. Ao documentar seus processos, você garante eficiência, consistência e tranquilidade para todos os envolvidos.
- Conheço as necessidades dos usuários do VLC porque sou um deles. Isso vai permitir que você escreva a documentação de forma que todos os usuários do mundo entendam de cara.