Projeto VLC

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:

VLC

Redator técnico:

Abhishek Pratap Singh

Nome do projeto:

Continuar a modernização da documentação do usuário do VLC

Duração do projeto:

Duração padrão (três meses)

Project description

STATUS ATUAL DA DOCUMENTAÇÃO

A documentação do usuário do VLC está sendo modernizada e atualizada. A transição está em andamento para ir da documentação mais antiga baseada em wiki[1] para a documentação de usuário moderna construída no Sphinx[2] hospedada no ReadTheDocs.

PÚBLICO-ALVO

O público-alvo é um usuário curioso que quer explorar os recursos do VLC Media Player além de um player de mídia comum e, em certa medida, também ajudará os desenvolvedores a servir como um guia de referência fácil. Por isso, pretendo incluir instruções baseadas em GUI (com imagens, quando relevantes) e métodos baseados em CLI (com snippets de código) para que o usuário final tenha liberdade de escolha.

Acredito que a linguagem da documentação (especialmente a seção da GUI) precisa ser simplificada o suficiente para que uma pessoa com exposição nominal ao funcionamento de computadores consiga entender e implementar o guia. Por outro lado, ela não deve ser muito longa ou explicativa (especialmente a seção de CLI) para que os programadores percam o interesse.

Para alcançar o equilíbrio certo, mencione pré-requisitos no início da página ou mantenha seções opcionais que os especialistas podem pular.

Para criar traduções, o público-alvo é de desenvolvedores/usuários do VLC com bom domínio do inglês e do idioma para o qual a tradução será feita.

FERRAMENTAS

A nova documentação está sendo criada pelo Sphinx e hospedada no ReadTheDocs, e o sistema de controle de versões está implementado no GitLab. Tive alguma experiência anterior com o Git e o GitHub, o que me ajudou a aprender a usar o GitLab, embora alguns recursos diferentes precisem de um tempo para serem aprendidos.

Eu li sobre o Sphinx quando um colega entusiasta de código aberto comentou que muitas organizações estavam usando a ferramenta para criar a documentação, como o Blender, que usa o Sphinx para criar o Manual do Usuário[3] e a documentação da API[4].

Eu conhecia um pouco o ReadTheDocs, que é uma boa ferramenta para controle de versões e hospedagem de documentação técnica. Por isso, consegui criar a documentação do VLC sem muitos problemas e já conheço o reStructured Text, a formatação usada.

Para traduções, o VLC usa o Babel para gerar arquivos .po e implementar i18n e l10n. Atualmente, estou me familiarizando com o fluxo de trabalho do Babel e como criar arquivos .mo usando o Sphinx.

Pretendo usar o período de vinculação para me familiarizar ainda mais com as complexidades das ferramentas mencionadas acima.

ENTREGAS E CRONOGRAMA SEMANAL

Como parte do projeto de 2019, partes da instalação, interface, áudio, vídeo, reprodução etc. (a maioria das funcionalidades básicas) já foram cobertas. Por isso, para o projeto de 2020, gostaria de atualizar e trabalhar na seção de uso avançado da documentação do usuário.

ENTREGA 1 [Semana 1-2]: atualizar a documentação do Transcode, conforme mencionado em #7[5].

• transcodificar
• Transcodificar vários vídeos
• Adicionar um logotipo
• Mesclar vídeos
• Extrair áudio e Extrair áudio de um arquivo
• Extrair um DVD

PRODUTO 2 [Semana 3-4]: atualizar o uso do VLC como um plug-in da Web[6], testando no Firefox 77, Chrome 83 e Edge 83.

• Como criar páginas da Web com vídeos
• Atributos de tags incorporadas
• Descrição da API JavaScript

ENTREGA 3 [Semana 5]: Teste os comandos da interface de linha de comando[7] e atualize de acordo.

• Streams
• Seleção de módulos
• Opções específicas do item
• Filtros

Semana 6: semana de reserva para as três entregas acima.

ENTREGA 4 [Semana 7-8]: se preparar para as traduções. Além de atualizar, vou preparar traduções para outros idiomas. Isso é importante porque, após a tradução, os usuários que não têm conhecimento do inglês poderão ler a documentação. Além disso, o VLC estaria mais perto de conquistar o domínio do mundo[8].

Conforme mencionado na seção "Ferramentas" da proposta, o VLC atualmente usa o Babel para gerar arquivos .po para traduções. Documento o processo para um usuário/voluntário para:

• Faça o download e crie a documentação básica localmente.
• Use o Babel para gerar os arquivos necessários.
• Insira as traduções das strings.
• Criar a documentação traduzida usando o Sphinx.
• Faça commit das alterações.

ENTREGA 5 [Semana 9-10]: Prepare-se para a documentação dos módulos. Conforme conversado com os mentores, pretendo me preparar para a documentação dos módulos em duas partes.

Parte I: criar arquivos próximos aos módulos usando um script que procura opções válidas na base de código e extrai o uso de uma linha (e os valores padrão) das páginas de wiki correspondentes. Isso serviria como rascunho básico.

Parte II: como criar uma estrutura específica para a plataforma que vincula todos os módulos, plug-ins e opções de uma plataforma específica (Windows e, se houver tempo, também para Fedora).

Criar arquivos perto dos módulos garante que a documentação fique próxima do código-fonte. Usando uma abordagem de baixo para cima, a documentação principal dos módulos seria criada combinando os arquivos feitos na Parte I e usando a estrutura feita na Parte II como referência.

Os arquivos criados pela automação precisam de uma revisão, mas a primeira prioridade é criar um framework funcional. Depois disso, e de acordo com o tempo disponível, eu analisaria os arquivos para verificar as opções. O framework está sendo priorizado, porque, assim que estiver disponível, os desenvolvedores e mantenedores também poderão começar a contribuir adicionando casos de uso relevantes.

BÔNUS ENTREGUE [Semana 11]: Prepare-se para o lançamento da versão 4.0. Caso o projeto continue no cronograma, gostaria de propor um bônus. Conforme discutido com os mentores, a preparação para a versão 4.0 implica ter uma documentação estável e quase completa para a versão 3.0.

Por isso, eu verificaria a documentação já concluída das seguintes seções para verificar e atualizar os métodos mencionados:

• Uso básico: mídia, reprodução, áudio, vídeo, legendas, atalhos, gravações, configurações, dicas e truques.
• Uso avançado: player, interface, transcodificação, streaming, casos incomuns.
• Complementos: extensões, skins.

Semana 12: Semana de reserva para os três resultados acima + Relatórios finais.

POR QUE SOU A PESSOA CERTA PARA ESTE PROJETO?

Como entusiasta de tecnologia, tenho experiência no uso/teste de software e, às vezes, tento entender as bases de código. Na verdade, tentar entender a base de código de uma organização de código aberto foi a primeira vez que percebi a importância da documentação. Além disso, como um entusiasta da música, tenho muita experiência em fazer ajustes no VLC :)

Além disso, sou pesquisador e escritor a vida toda. Se não anotar algo, nunca vou entender de verdade, e esse hábito me tornou um bom tomador de notas e documentador.

A interseção desses dois hábitos é o que me torna uma pessoa adequada para documentação técnica. Posso entender os aspectos técnicos e documentar minhas descobertas/processos de uma forma que os usuários entendam.

Links: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35