Projeto VideoLAN

Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:

VideoLAN

Redator técnico:

Edidiong Anny Asikpo

Nome do projeto:

Modernize (reescreva) a documentação do usuário do VLC

Duração do projeto:

Duração padrão (3 meses)

Project description

ABSTRATA

Uma documentação do Usuário foi criada 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: uma boa documentação ao usuário é um sinal de integridade do produto, a equipe de desenvolvimento.

Sem uma boa documentação do usuário, um usuário pode não saber como fazer as coisas acima de forma eficaz e eficiente. As documentações do usuário podem desempenhar um papel fundamental para garantir o sucesso de um produto, pois uma ótima comunicação é e sempre será o centro de qualquer negócio ou produto, e uma ótima documentação apenas pega essa comunicação e a coloca em uma estrutura 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 VLC Media Player era transferido por download aproximadamente 23 milhões de vezes por mês no site principal. Isso mostra que muitas pessoas no mundo todo usam o VLC Media Player e talvez queiram ler a documentação do usuário para receber orientações sobre como usá-lo. No entanto, a documentação do usuário do player de mídia do VLC está desatualizada e incompleta (foi modificada pela última vez no dia 28 de outubro de 2015), e 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

Atualmente, a documentação do usuário está disponível em uma página wiki. Ele está obsoleto, incompleto, difícil de navegar ou encontrar informações, não cobre informações sobre a versão atual do player de mídia e só pode ser traduzido para alemão, o que causa um grande problema para pessoas que não sabem ler o idioma.

POR QUE MINHA DOCUMENTAÇÃO DO 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 um usuário final. Ele contém guias por escrito e imagens associadas, além de incluir 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, 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 e ele compartilhou dois links que mostravam um repositório Gitlab do arquivo fonte escrito com o Sphinx e a documentação principal hospedada no Read the Docs. Ele disse que eles esperam que a nova documentação seja semelhante a ela. Pesquisei muito 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 uma série de recursos esperados pelos redatores, como publicação de fonte única, reutilização de conteúdo por inclusões, inclusões condicionais baseadas no tipo de conteúdo e nas tags, diversos temas HTML maduros que proporcionam uma ótima experiência do usuário em dispositivos móveis e computadores, referência em páginas, documentos e projetos. Suporte para índice e glossário e suporte para 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.

Leia a documentação

Leia os Documentos simplifica a documentação de software automatizando a criação, o controle de versões e a hospedagem de seus documentos para você. Ele nunca sai de sincronia, ou seja, sempre que você envia código para seu sistema de controle de versões favorito, seja Git, Mercurial, Bazaar ou Subversion, o Read the Docs cria seus documentos automaticamente para que seu código e documentação estejam sempre atualizados. Ele tem várias versões. O Read the Docs pode hospedar e criar várias versões de seus documentos, portanto, ter uma versão 1.0 de seus documentos e uma versão 2.0 de seus documentos é tão fácil quanto ter um branch ou tag separado em seu sistema de controle de versão. 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 computadores.

VEREDITO

O Sphinx é uma ferramenta incrivelmente poderosa e o Read the Docs baseia-se para fornecer hospedagem para documentação do Sphinx que mantém seus documentos atualizados em todas as versões. Juntos, eles formam um conjunto maravilhoso de ferramentas que desenvolvedores e redatores técnicos podem usar para criar documentação do usuário que seria a melhor para os usuários finais.

O Sphinx inclui suporte à tradução de 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 alterações sejam revisadas antes de serem mescladas com o repositório principal. O controle de versões também vai aumentar a contribuição de código aberto para o projeto, porque as pessoas podem criar problemas, abrir solicitações de envio etc. O Sphinx e a leitura dos documentos são usados por uma lista de outras grandes comunidades, como ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, e é uma ótima ferramenta para usar na nova documentação do usuário do VLC.

Além de ler sobre essas ferramentas, criei uma amostra básica. Este é o link: https://gitlab.com/Didicodes/demo-vlc-user-documentation para o meu repositório do Gitlab. 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 dessa nova estrutura, ela precisa ser aprovada pelos mentores. Isso significa que a estrutura provavelmente mudará depois de ser revisada pelos mentores.

METAS DO PROJETO

• Reestruturar a documentação.
• Atualize a documentação para se adequar às versões modernas do VLC.
• Migrar a documentação do usuário para o Gitlab usando Sphinx e ReadtheDocs.
• Remover imagens e informações obsoletas.
• Reescrever a documentação do usuário para facilitar a compreensão.
• Configure-o para tradução usando a internacionalização Sphinx.
• Torne a documentação orientada pela comunidade para que os usuários possam informar ou resolver quaisquer problemas encontrados ao ler a documentação.

POR QUE ESTE PROJETO?

Sempre tive a convicção de que escrever códigos, resolver problemas e desenvolver softwares atinge seu potencial máximo quando você também tem a capacidade de esclarecer as outras pessoas sobre isso por meio da escrita. Pessoalmente, sempre fui fascinado pelos esforços da comunidade da VideoLAN na criação de soluções de software sem custo financeiro para multimídia. Quando eu era criança, o VLC Media player era o software que eu usava para ouvir música ou assistir um filme, porque era muito barulhento e consistia em 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 em melhorar a documentação de organizações e posso usar qualquer sistema de controle de versão, então executar comandos no Gitab não será um problema. Além disso, o que me move é trabalhar em projetos que criam valor para as pessoas.
• Acredito que se você quer que alguém faça algo da maneira mais eficiente possível, documente 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 eu sou um deles. Isso permitirá escrever a documentação de uma maneira que todos os outros usuários ao redor do mundo entendam rapidamente.