Esta página foi traduzida pela API Cloud Translation.

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:: Avii
Nome do projeto:: Criar a documentação do usuário do VLC para uma porta de dispositivo móvel (Android)
Duração do projeto:: Duração padrão (3 meses)

Project description

ABSTRATA

A documentação do usuário é usada como um sistema de suporte estático para auxiliar os usuários finais. Ela fornece informações técnicas e não técnicas sobre um produto ou serviço. Ajuda os usuários a aprender a usar o software ou serviço. Nem todo mundo quer entrar em contato com o suporte ou aguardar uma resposta por e-mail se só precisa de uma orientação, dicas ou truque. A documentação do usuário faz isso. Também reduz os custos de suporte e é uma identificação da integridade do produto e da equipe de desenvolvimento.

O VLC para Android já teve mais de 100 milhões de downloads apenas na Google Play Store. O VLC oferece muitos recursos para as portas móveis, desde reprodução de áudio e vídeo até streaming de rede. Muitas vezes, as pessoas querem usar esses recursos incríveis, mas não conseguem. Pesquisar um blog ou algum vídeo aleatório para isso requer muito tempo e paciência e, mesmo assim, não há autenticidade das informações recebidas. Atualmente, o VLC hospeda a documentação do usuário do VLC para Android na página wiki e fornece menos ou nenhuma descrição desses recursos. Além disso, as páginas wiki foram atualizadas pela última vez em março de 2019. O projeto atual fornecerá uma nova documentação do usuário com um design moderno e maior facilidade de uso para a porta do Android.

SITUAÇÃO ATUAL

As páginas da wiki estão completamente desatualizadas e contêm muito menos informações sobre a versão mais recente do VLC. Além disso, eles não são fáceis de navegar. Não há opção visível para ler a documentação em outro idioma além do inglês. Não contém descrições de recursos.

ANÁLISE

-> No momento, a documentação atual está obsoleta e precisa ser escrita de uma maneira nova, usando uma plataforma e ferramentas diferentes.

-> A maioria dos usuários de Android tem pouco ou nenhum conhecimento técnico. No entanto, há pessoas que precisam de informações mais técnicas sobre um recurso. Não é uma boa ideia escrever e manter duas documentações separadas para cada uma das finalidades acima. Ou mesmo na mesma documentação, dividir um recurso com base em aspectos técnicos e não técnicos cria confusão adicional. Como a maioria dos usuários está acostumada à interface que vê ou aos recursos que usa, nem todos sabem se algo é técnico ou não. Queremos simplificar isso para eles.

-> A maioria dos usuários vai tentar acessar informações pelo próprio smartphone e usar um computador ou outros dispositivos para acessar as informações. Portanto, a documentação deve ser facilmente adaptável a cada tamanho de tela. e não criar confusão sobre a navegação.

-> Nem todos os recursos da versão para desktop estão disponíveis na porta do Android e, se disponíveis, não funcionam da mesma forma nas duas portas. Isso ocorre porque o aplicativo para computador está em desenvolvimento há muito tempo e atingiu um tipo de estado de saturação. Por outro lado, a porta para dispositivos móveis é relativamente nova e ainda está em desenvolvimento. Além disso, os dispositivos móveis estão se tornando tão potentes hoje em dia, mas há uma restrição óbvia no tipo de recurso que podemos incorporar principalmente devido à demanda do usuário final. Ter um recurso que ninguém usa é desperdício de recursos de desenvolvimento. Portanto, não é recomendável converter as duas documentações com base nos recursos.

COM BASE NA ANÁLISE ACIMA, APRESENTO O SEGUINTE. 1. No momento, a documentação do usuário para computador usa o gerador de documentação do Sphinx e o tema Ler o Documentos. Usar o mesmo para a porta do Android nos ajudará das seguintes maneiras: -> Fácil fusão das duas documentações. -> É otimizado para todos os tamanhos de tela. -> Experiência tranquila ao navegar para a documentação do usuário do Android pela documentação no computador

Separar os capítulos, seções e subseções de acordo com a posição relativa na aplicação. Por exemplo, o modo de plano de fundo/PiP fica em "Mais" -> "Configurações"->"Vídeo". A estrutura dos capítulos será

Mais

|__Configurações

| |__Biblioteca de mídia

| |__Vídeo -->Modo de segundo plano/PiP

: -> Essa abordagem facilita o acesso porque os usuários podem navegar facilmente até a parte onde precisam de ajuda, comparando-a à localização relativa no aplicativo. Para cada recurso, podemos separar as partes técnicas e não técnicas. Primeiro, vamos escrever uma descrição fácil não técnica e depois destacar ou rotular as partes técnicas do mesmo recurso, se houver, logo abaixo dele. Isso pode gerar repetições, mas garante uma boa experiência da maioria não técnica. Isso também será útil no futuro porque aumentará a capacidade de manutenção. Como o aplicativo atingirá o estado de saturação, é pouco provável que a IU relativa mude muito. Portanto, no futuro, se um novo recurso for adicionado/removido, poderemos simplesmente refatorar a seção. Caso toda a interface mude, podemos reorganizar as seções/capítulos ou reestruturar todo o documento. Em qualquer caso, precisamos modificar toda a documentação, porque a captura de tela terá que ser substituída para corresponder à interface atual. Uma demonstração funcional está hospedada aqui : https://avinal.gitlab.io/vlc-android-docs/
Cada seção da documentação deve consistir em uma captura de tela rotulada, descrição do recurso, parte mais técnica, se houver, e dicas e truques do recurso.

-> O desenvolvimento independente dessa documentação do usuário a partir do computador nos ajudará a mesclar os documentos em apenas algumas etapas, sem afetar a documentação atual ou ser afetado por ela durante o desenvolvimento. Proponho colocar toda essa documentação na seção do Android da documentação para computadores depois de desenvolvida e criar um link permanente para a documentação do VLC para Android.

-> Mais melhorias podem incluir a reformulação da página inicial da documentação do usuário para computadores para permitir que os usuários escolham diretamente seu sistema operacional favorito e, em seguida, redirecionamento para a documentação do SO escolhido. Como a documentação do usuário do Windows, MacOS e Linux VLC já foi bem elaborada e convertida, é possível escolher entre Windows/MacOS/Linux ou Android ou iOS. Isso resultará em uma documentação do usuário bem separada, mas unificada, com apenas um link para usar em todas as portas.

POR QUE MINHA DOCUMENTAÇÃO PROPOSTA DO USUÁRIO É MELHOR? Essa documentação do usuário proposta é estruturada com base nos padrões comuns seguidos pelo usuário final para obter ajuda. A documentação combina todos os recursos necessários, como simplicidade, clareza, aparência e conhecimento tecnológico, para maximizar a facilidade de uso e a experiência do usuário final. Isso também é fácil de manter, já que não é mais necessário manter a documentação do usuário individual para cada porta.

POR QUE SOU A PESSOA CERTA PARA ESTE PROJETO? -> Escrevo códigos há dois anos e, com frequência, preciso repassar a documentação da API de determinadas bibliotecas ou de algum software ou até mesmo documentar meu próprio código. Então, eu sei exatamente o que as pessoas querem ver na documentação, que problema elas enfrentam e como abordam para conseguir ajuda. Poderei aplicar a mesma experiência para escrever uma documentação consistente e de fácil leitura.

-> Tenho escrito ativamente materiais técnicos no Quora, Stack Overflow e em várias outras plataformas. Sei explicar as coisas de uma maneira que seja cativante e as pessoas entendam facilmente.

-> O VLC para Android é uma ferramenta poderosa e muito famosa, mas a maioria dos recursos é desconhecida ou não há ajuda disponível. Já uso o VLC em plataformas para computadores e dispositivos móveis há muitos anos e sei quais problemas o usuário pode enfrentar. Com todo meu conhecimento e experiência posso garantir uma ótima documentação.