Projeto VLC

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:

VC

Redator técnico:

Abhishek Pratap Singh

Nome do projeto:

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

Duração do projeto:

Duração padrão (3 meses)

Project description

STATUS ATUAL DA DOCUMENTAÇÃO

A documentação do usuário do VLC está em processo de modernização e atualização. A transição está em andamento: da documentação mais antiga baseada em wiki[1] para a documentação do usuário moderna criada pelo sphinx[2] hospedada em ReadTheDocs.

PÚBLICO-ALVO

O público-alvo é um usuário curioso que quer explorar os recursos do player de mídia VLC além de um player de mídia comum e, até certo ponto, ele também ajuda os desenvolvedores, servindo como um guia de referência fácil. Por isso, pretendo incluir instruções baseadas em GUI (junto de imagens quando relevante) e métodos baseados em CLI (junto 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 GUI) deve ser reduzida o suficiente para que uma pessoa com exposição nominal a computadores operacionais possa entender e implementar o guia. Por outro lado, os desenvolvedores não podem ser muito longos nem explicativos (especialmente a seção da CLI).

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

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

FERRAMENTAS

A nova documentação está sendo criada pelo Sphinx e hospedada no ReadTheDocs, e o sistema de controle de versões foi implementado no GitLab. Eu tive alguma experiência com o Git e o GitHub, o que me ajudou a pegar o jeito do GitLab, embora tenha levado algum tempo para aprender sobre determinados recursos diferentes.

Quanto ao Sphinx, eu li sobre isso quando um colega entusiasta de código aberto observou quantas organizações o estão usando para construir sua documentação (com o exemplo notável do Blender, que usa o Sphinx para criar seu Manual do Usuário[3] e Documentação de API[4]).

Eu conhecia 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 estou familiarizado com o texto reestruturado, a formatação usada.

Para traduções, o VLC está usando o Babel para gerar arquivos .po e implementar a i18n e l10n. Atualmente, estou me familiarizando com o fluxo de trabalho do Babel e com a criação de arquivos .mo usando o Sphinx.

Pretendo usar esse período para me familiarizar ainda mais com as complexidades das ferramentas mencionadas acima.

ENTREGAS E CRONOGRAMA SEMANAL

Como parte do projeto de 2019, partes de instalação, interface, áudio, vídeo, reprodução etc. (a maioria das funcionalidades básicas) já foram abordadas. 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 [Semana1-2]: Atualize a documentação de transcodificação, conforme mencionado na pergunta 7[5].

• Transcodificação
• Transcodificar vários vídeos
• Adicionar um logotipo
• Combinar vídeos
• Extrair áudio e extrair áudio de um arquivo
• Rasgue um DVD

ENTREGA 2 [Semana 3-4]: Atualize usando o VLC como um plug-in da Web[6] e teste no Firefox 77, Chrome 83 e Edge 83.

• Como criar páginas da Web com vídeos
• Incorporar atributos da tag
• Descrição da API JavaScript

ENTREGA 3 [Semana 5]: teste os comandos da Interface de linha de comando[7] e faça as atualizações necessárias.

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

Semana 6: Semana Buffer para as três entregas acima.

ENTREGAR 4 [Semana 7 a 8]: prepare-se para traduzir. Além de atualizar, vou me preparar para traduções para outros idiomas. Isso é importante porque, após a tradução, usuários sem experiência em inglês conseguiriam ler a documentação e, para observação, o VLC estaria um passo mais perto de conquistar o domínio mundial[8].

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

• Faça o download e crie a documentação de base localmente.
• Use o Babel para gerar os arquivos necessários.
• Insira "Traduções" para as strings.
• Criação da documentação traduzida usando o Sphinx.
• Confirme as mudanças.

DELIVERABLE 5 [Semana 9-10]: preparação para a documentação dos módulos. Conforme discutido 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 por meio de um script que procura opções válidas na base do código e extrai o uso de uma linha (e valores padrão) das páginas wiki correspondentes. Isso serviria como um rascunho básico.

Parte II: criação de uma estrutura específica da plataforma que vincule todos os módulos+plug-ins+opções de uma plataforma específica (para Windows e, se houver tempo, também para o Fedora).

Criar arquivos próximos aos módulos garante que a documentação esteja próxima ao código-fonte. Usando uma abordagem de baixo para cima, a Documentação principal dos Módulos seria criada a partir da combinação dos arquivos feitos na Parte I e usando a estrutura feita na Parte - II como referência.

Os arquivos criados pela automação precisam de revisão, mas a primeira prioridade é criar uma estrutura 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 assim que for disponibilizado, os desenvolvedores e mantenedores também poderão começar a contribuir adicionando casos de uso relevantes.

ENTREGA DE BÔNUS [Semana 11]: prepare-se para o lançamento da versão 4.0. Caso o projeto permaneça dentro do cronograma, eu gostaria de propor uma entrega de bônus. Conforme discutido com os mentores, preparar-se para a versão 4.0 implica ter uma documentação estável e quase completa para a versão 3.0.

Portanto, eu gostaria de analisar a documentação já completa das seções a seguir para verificar e atualizar os métodos mencionados:

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

Semana 12: Semana Buffer para as três entregas acima + Relatórios finais.

POR QUE SOU A PESSOA CERTA PARA ESTE PROJETO?

Como entusiasta da tecnologia, tenho experiência com o uso/teste de software e, às vezes, tentando entender a base de código deles. Na verdade, tentar entender a base do código de uma organização de código aberto foi a primeira vez que eu realmente percebi a importância da documentação. Além disso, como entusiasta de música, tenho muita experiência em ajustar com o VLC :)

Além disso, sou pesquisadora e escritora o tempo todo. A menos que eu escreva algo, nunca entendo de verdade, e esse hábito me tornou uma anotador e documentador eficiente.

A interseção desses dois hábitos é o que me torna a pessoa certa para a documentação técnica. Consigo encontrar os aspectos técnicos e documentar minhas descobertas/processos de uma maneira que os usuários entendam.

Links: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-docs.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.wikiblender.org/api/current/index.org/api/current/index.org-[5] https://docs.blender.org/manual/en/latest/