Esta página foi traduzida pela API Cloud Translation.

Projeto VideoLAN

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:: 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

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. 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 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 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.

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 é 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 usar o player de mídia. 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). Por isso, 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 do VLC.

ESTADO ATUAL

Atualmente, a documentação do usuário está disponível em uma página wiki. Ela está obsoleta, incompleta, 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 traduzida em alemão, o que causa um grande problema para pessoas que não sabem ler o idioma.

POR QUE MINHA DOCUMENTAÇÃO PROPOSTA DO USUÁRIO É UMA MELHORIA EM RELAÇÃO A A 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, incluir instruções e explicações sobre como usar cada recurso do player de mídia VLC, 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. 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 "Ler os documentos". Ele disse que esperaria que a nova documentação fosse 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 que os redatores esperam, como publicação de fonte única, reutilização de conteúdo por inclusões, inclusões condicionais com base no tipo de conteúdo e tags, vários temas HTML maduros que oferecem uma ótima experiência do usuário em dispositivos móveis e computadores, referenciando páginas, documentos e projetos Suporte ao í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 documentação.

Ler 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ão favorito, seja Git, Mercurial, Bazaar ou Subversion, o Read the Docs cria seus documentos automaticamente para que seu código e sua documentação estejam sempre atualizados. Ele tem várias versões. O Ler os documentos pode hospedar e compilar várias versões de seus documentos, portanto, ter uma versão 1.0 e uma versão 2.0 de seus documentos é tão fácil quanto ter uma ramificação ou tag separada em seu sistema de controle de versões. O Documentos Google é sem custo financeiro,tem código aberto e hospeda documentação de quase 100 mil projetos de código aberto grandes e pequenos em quase todas as linguagens humanas e de computadores.

VERDIÇÃO

O Sphinx é uma ferramenta incrivelmente poderosa, e o recurso Leia os documentos está baseado para fornecer hospedagem para a documentação do Sphinx que mantém seus documentos atualizados em todas as versões. Juntas, elas formam um conjunto maravilhoso de ferramentas que desenvolvedores e redatores técnicos podem usar para criar documentação do usuário que seja a melhor para os usuários finais.

O Sphinx inclui suporte para a tradução de documentação em 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 ao repositório principal. O controle de versões também fará a documentação 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 meu repositório do Gitlab. A versão hospedada em readthedocs pode ser encontrada aqui: [https://vlc-user-document-demo.readthedocs.io/en/latest/](https://vlc-user-document-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 consultada aqui: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Antes de começar a implementação dessa nova estrutura, ela precisa ser aprovada pelos mentores. Isso significa que é provável que a estrutura mude 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.
Migre a documentação do usuário para o Gitlab usando o Sphinx e o ReadtheDocs.
Remova imagens e informações obsoletas.
Reescrever a documentação do usuário para facilitar o entendimento.
Configure-o para tradução usando a internacionalização do Sphinx.
Incentive a documentação pela comunidade para que os usuários possam informar ou resolver problemas encontrados durante a leitura.

POR QUE ESTE PROJETO?

Sempre tive a convicção de que escrever código, resolver problemas e criar software atinge todo o seu potencial quando você também tem a capacidade de esclarecer as pessoas sobre isso por meio da escrita. Pessoalmente, sempre fui fascinado pelos esforços da comunidade do 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 ele era muito barulhento 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 em melhoria da documentação de organizações e posso usar qualquer sistema de controle de versão. Portanto, 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, 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 eu sou um deles. Isso permitirá redigir a documentação de modo que todos os outros usuários ao redor do mundo entendam imediatamente.