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 o Temporada dos Documentos Google.

Resumo do projeto

Organização de código aberto:: VLC
Redator técnico:: Avii
Nome do projeto:: Criar a documentação do usuário do VLC para uma porta móvel (Android)
Duração do projeto:: Duração padrão (três meses)

Project description

ABSTRATA

A documentação do usuário é usada como um sistema de suporte estático para ajudar os usuários finais. Ele fornece informações técnicas e não técnicas sobre um produto ou serviço. Ele ajuda os usuários a aprender a usar o software ou serviço. Nem todo usuário quer entrar em contato com o suporte ou esperar por uma resposta por e-mail se tudo o que ele precisa é de uma pequena orientação, dicas ou truques. A documentação do usuário faz isso. Isso também reduz os custos de suporte e é uma identidade da saúde do produto e da equipe de desenvolvedores.

O VLC for Android foi baixado mais de 100 milhões de vezes na Google Play Store. O VLC oferece diversos 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, ainda assim, não há autenticidade das informações obtidas. Atualmente, o VLC hospeda a documentação do usuário do VLC para Android na página do wiki e fornece uma descrição menor ou nenhuma desses recursos. Além disso, as páginas da Wiki foram atualizadas pela última vez em março de 2019. O projeto atual vai oferecer 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 wiki estão completamente desatualizadas e contêm muito menos informações sobre a versão mais recente do VLC. Além disso, não é fácil navegar neles. Não há uma opção visível para ler a documentação em outro idioma além do inglês. Ele não contém descrições de recursos.

ANÁLISE

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

-> A maioria dos usuários do Android tem pouco ou nenhum conhecimento técnico. No entanto, algumas pessoas precisam de informações mais técnicas sobre um recurso. Escrever e manter duas documentações separadas para cada uma das finalidades acima não é uma boa ideia. Ou até mesmo na mesma documentação, dividir um recurso baseado em aspectos técnicos e não técnicos cria ainda mais confusão. Como a maioria dos usuários está acostumada com a interface ou os recursos usados, isso não é fácil para todos decidirem se algo é técnico ou não. Então, queremos simplificar isso para eles.

-> A maioria dos usuários vai tentar acessar informações pelo smartphone e o restante por computadores ou outros dispositivos. Portanto, a documentação precisa ser facilmente adaptável a todos os tamanhos de tela. E não deve criar confusão sobre a navegação.

-> Nem todos os recursos da versão para computador estão disponíveis na porta 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 mais tempo e atingiu um tipo de estado de saturação. Já a porta para dispositivos móveis é relativamente nova e ainda está em desenvolvimento. Além disso, embora os dispositivos móveis de hoje em dia estejam se tornando muito poderosos, 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 comparar a documentação com base nos recursos.

COM BASE NA ANÁLISE ACIMA, PROPOSTO O SEGUINTE. 1. No momento, a documentação do usuário para computadores está usando o gerador de documentação do Sphinx e o tema "Ler o documento". Usar o mesmo para a porta Android nos ajudará das seguintes maneiras: -> Fusão fácil das duas documentações. -> Ele é otimizado para todos os tamanhos de tela. -> Experiência integrada ao navegar para a documentação do usuário do Android pela documentação para computador

Separar os capítulos, as seções e as subseções de acordo com a posição relativa no aplicativo. Por exemplo, o modo de segundo plano/PiP está em "Mais" -> "Configurações" -> "Vídeo". Portanto, a estrutura do capítulo será

Mais

|__Configurações

| |__Biblioteca de mídia

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

: -> Essa abordagem vai melhorar a facilidade de acesso, já que os usuários poderão navegar facilmente até a parte em que precisam de ajuda, comparando-a com a localização relativa no aplicativo. Para cada recurso, podemos separar ainda mais as partes técnicas e não técnicas. Primeiro, vamos escrever uma descrição fácil e não técnica e, em seguida, destacar ou rotular as partes técnicas do mesmo recurso, se houver, logo abaixo. Isso pode levar a algumas repetições, mas vai garantir uma experiência tranquila para a maioria não técnica. Isso também ajudará no futuro, aumentando a capacidade de manutenção. Como o aplicativo vai atingir o estado de saturação, a interface relativa não vai mudar muito. Portanto, no futuro, se um novo recurso for adicionado/removido, vamos apenas refatorar a seção. Caso toda a IU seja alterada, podemos reorganizar as seções/capítulos ou reestruturar todo o documento. Nos dois casos, 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 marcada, descrição do recurso, parte mais técnica, se houver, e dicas e truques para o recurso.

-> O desenvolvimento independente dessa documentação do usuário no computador nos ajudará a mesclar as duas documentações 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 Android da documentação para computadores depois que ela for desenvolvida e, em seguida, criar um link permanente para a documentação do VLC para Android.

-> Outras melhorias podem incluir o redesenho da página inicial da documentação do usuário para computadores para permitir que os usuários escolham diretamente o SO favorito e sejam redirecionados para a documentação do SO escolhido. Como a documentação do usuário do VLC para Windows, MacOS e Linux já está bem projetada e conversada, podemos colocar opções para escolher entre Windows/MacOS/Linux ou Android ou iOS. Isso vai 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 DE USUÁRIO PROPOSTA É MELHOR? A documentação proposta para o usuário é estruturada com base nos padrões comuns seguidos pelo usuário final para receber ajuda. A documentação combina todos os recursos necessários, por exemplo, 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, porque não é mais necessário manter a documentação individual do usuário em cada porta.

POR QUE SOU A PESSOA CERTA PARA ESTE PROJETO? -> Escrevo códigos há dois anos e, muitas vezes, preciso ler a documentação da API de algumas bibliotecas ou 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, qual problema elas enfrentam e como elas abordam para obter ajuda. Vou poder aplicar a mesma experiência para escrever uma documentação consistente e fácil de ler.

-> Tenho escrito coisas técnicas no Quora, Stack Overflow e várias outras plataformas. Sei como explicar as coisas de uma forma cativante e as pessoas entenderem facilmente.

-> O VLC para Android é uma ferramenta poderosa e muito conhecida, mas a maioria dos recursos é desconhecida ou não há ajuda disponível. Uso o VLC em plataformas para computadores e dispositivos móveis há muitos anos e sei os problemas que os usuários podem enfrentar. Combinando todo o meu conhecimento e experiência, posso garantir uma ótima documentação.