O projeto da Fundação Wikimedia

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:
Fundação Wikimedia
Redator técnico:
Pavithra Eswaramoorthy
Nome do projeto:
Melhoria da documentação para documentaristas técnicos e cinegrafistas do Wikimedia
Duração do projeto:
Duração padrão (3 meses)

Project description

1. Sobre mim

Foi apresentado o software de código aberto alguns meses atrás e, quase imediatamente, me senti sobrecarregado pelo escopo ilimitado. Tendo dificuldade em percorrer os zilhões de projetos, aprendi sobre iniciativas de código aberto, como o Google Summer of Code e o Partnershipy. A temporada de documentos do Google parecia interessante, e as ideias de projetos da Fundação Wikimedia despertaram minha curiosidade, então comecei a explorar mais.

Até agora, minha jornada tem sido emocionante e confusa, cheia de perguntas como "Espere, o quê?", "Ahh, eu entendo!" e "Devo comentar sobre isso?". A comunidade do Wikimedia me apoiou a cada etapa. Desde edição de páginas até a criação de extensões, aprendi algo novo todos os dias.

Como esperado, o processo de inscrição serviu como minha porta de entrada para a comunidade de código aberto. Esta proposta é inspirada nas minhas próprias experiências como iniciante.

2. Projeto

2.1. Contorno

Este projeto visa melhorar a documentação para escritores técnicos e cinegrafistas potenciais em toda a Wikimedia. Um conjunto maduro de diretrizes de documentação técnica ajudaria a promover uma documentação geral aprimorada, e as referências para a criação de screencasts permitiriam a demonstração dos recursos do software de maneira eficaz. A documentação existente nessas áreas pode ser estendida para oferecer um suporte melhor a novos colaboradores e colaboradores experientes. Uma abordagem incremental será adotada para desenvolver essa rede de recursos úteis.

2.2. Resultados

  • T197006 [https://phabricator.wikimedia.org/T197006] (link em inglês): melhoria da documentação para documentaristas do Wikimedia:

    • Adicione dicas e exemplos ao guia de documentação/estilo. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Adicione informações específicas da MediaWiki a determinados gêneros em modelos e sugestões de documentação técnica: guias do usuário, instruções, guias de início rápido, notas de versão e READMEs. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Teste e aprimore as diretrizes de priorização de documentação técnica. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Criar uma estratégia de coleta de conteúdo para diferentes gêneros de documentação.
    • Criar uma estratégia de comunicação e colaboração para a documentação do MediaWiki.
    • Crie uma lista de verificação para que os redatores possam revisar os documentos antes da publicação.
    • Expandir a estrutura da documentação para novos redatores técnicos. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Selecionar uma lista de tarefas de documentação técnica adequadas para hackatons. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Crie um hub para redatores técnicos que aponte para recursos úteis.

  • Melhore a documentação para cinegrafistas do MediaWiki:

    • Crie um guia do usuário rápido para fazer um screencast geral.
    • Crie modelos de screencast específicos do MediaWiki para tutoriais e instruções.

  • T214522 [https://phabricator.wikimedia.org/T214522]: crie um screencast de "Introdução ao Phabricator".

2.3. Objetivo de alongamento

  • Verifique novamente o conteúdo e atualize a documentação do WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentores

O Zulip será a principal forma de comunicação com meus mentores. Os canais IRC e o e-mail do Wikimedia serão usados para discussões com a comunidade. As discussões sobre tarefas específicas acontecerão na seção de comentários das tarefas do Phabricator.

4. Discussão

Este projeto é amplamente dividido em duas fases:

(i) Melhorar os recursos existentes para os redatores técnicos do Wikimedia.

(ii) Criar modelos úteis para possíveis cinegrafistas.

(i) Melhorar os recursos existentes para os redatores técnicos do Wikimedia.

No passado, houve várias iniciativas para melhorar a documentação do MediaWiki com diferentes graus de sucesso. Para citar alguns:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

A partir desses esforços, podemos entender que um conjunto melhor de recursos para escritores técnicos terá um impacto direto nos documentos gerados por eles.

Confira a seguir um snippet do relatório quinzenal de uma estagiária da plataforma 2018, Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

“O guia de estilo do MediaWiki está longe de ser perfeito, especialmente porque depende muito de referências externas sem destacar quais práticas considera as melhores. Esse problema não se limita apenas ao MediaWiki, já que ele aparece em outras documentações, como as práticas recomendadas de tradução. Os escritores acabam sem recursos bons e confiáveis para fazer seu trabalho, levando à dificuldade de estabelecer um público-alvo e um estilo adequado de escrita. E os usuários, especialmente os novos, podem ter problemas para entender novos conceitos e processos.”

T197006 [https://phabricator.wikimedia.org/T197006] também apresenta algumas áreas da documentação técnica de redação que precisam de melhorias. Obviamente, documentation/Style_guide é o lugar certo para começar.

Assim que tivermos um guia de estilo melhor, planejamos o próximo conjunto de documentos para orientar os escritores técnicos pelos diferentes estágios da redação técnica. Os documentos precisam ser fáceis de entender e, ao mesmo tempo, fornecer todas as informações necessárias para os escritores consultarem.

A etapa de preparação é possivelmente a mais importante, já que estabelece a base sobre a qual o documento será criado. Para auxiliar os redatores técnicos nessa fase, documentos de referência são desenvolvidos descrevendo algumas maneiras eficazes de reunir informações relevantes e dicas sobre como estruturar essas informações usando modelos.

Depois vem a etapa de escrita. Os escritores recebem exemplos de bons trabalhos para elevar o padrão automaticamente. Além disso, uma lista de verificação é criada com um conjunto de critérios básicos que todo documento deve seguir, o que ajudará os escritores a revisar seus documentos antes da publicação.

Mesmo com esses documentos, os novos redatores técnicos precisarão de ajuda extra, e precisamos dar isso a eles. O guia para novos escritores técnicos é refinado, e uma lista de tarefas adequadas para hackathons é selecionada com base no nível de dificuldade.

Por fim, um documento para entender o processo de gerenciamento e manutenção de documentação - "Priorização de documentação técnica" é testado e melhorado.

Ao final dessa fase, um hub de guias técnicos de redação, recursos, exemplos, sugestões e modelos será estabelecido de acordo com o guia de estilo da documentação.

(ii) Criar modelos úteis para possíveis cinegrafistas.

“Uma das maneiras mais difíceis de aprender qualquer coisa que envolva gráficos é lendo texto simples. Imagine também o que acontece se o manual se refere à versão errada do software. Com manuais somente de texto, muitas vezes é impossível recriar uma série de ações quando os menus e o texto do aplicativo mudam, já que faltam todas as dicas que usamos normalmente.

Talvez a melhor maneira de aprender seja com um especialista ao seu lado. Os screencasts ficam entre gráficos estáticos e com a atenção de um especialista. Nós conseguimos uma demonstração visual e móvel com uma voz amigável, além de anotações de texto na tela e animações. Uma vantagem dos screencasts em relação aos especialistas é que eles podem ser repetidos a cada hora, todos os dias.

Também podemos adicionar legendas traduzidas a um screencast para que possam ser assistidas por falantes não nativos ou substituir a faixa de áudio por idiomas alternativos.“

No trecho acima de "O manual do Screencasting" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald explica a importância de screencasts. Pode ser especialmente útil para tutoriais sobre como configurar o ambiente de desenvolvimento do MediaWiki, escrever extensões, usar o Gerrit e muito mais.

Assim como os modelos de documentos, ter um modelo padrão para screencasts promove a uniformidade, melhorando a experiência do espectador. Ele também oferece aos cinegrafistas em potencial uma estrutura para começar. Por isso, foi desenvolvido um guia rápido do usuário seguido de modelos para criar vídeos introdutórios e tutoriais. Os documentos incluem ponteiros sobre a profundidade dos conceitos a serem abordados e algumas ideias de screencast para o MediaWiki.

A melhor maneira de testar o modelo acima e se preparar para o novo objetivo é criar um screencast usando as ferramentas e os modelos. Por isso, criamos um screencast de “Introdução ao Phabricator” que cobre as noções básicas de uso do Phabricator. Esse processo também destacaria as áreas que precisam de discussão.

Por fim, a fonte central de referência para cinegrafistas do Wikimedia: o WikiProject Screencast é revisado e atualizado.

5. Linha do tempo provisória

Período de vínculo com a comunidade (1o de agosto a 1o de setembro)

  • Analisar o projeto em detalhes com meus mentores.

  • Discutir sobre:

    • com que frequência as tarefas precisam ser revisadas.
    • Compartilhe programações e decida sobre um fluxo de trabalho semanal/diário.
    • Ferramentas e recursos que podem ser usados.
    • Relatórios quinzenais e diários do projeto.

  • Crie as tarefas e subtarefas necessárias no Phabricator.

  • Crie rascunhos para compensar compromissos pessoais durante a fase de desenvolvimento do documento.

Semana 1 (de 2 a 8 de setembro)

  • Melhore a documentação/Style_guide:

    • Mude o foco principal para ilustrar as práticas recomendadas e os padrões do MediaWiki.
    • Inclua exemplos de bom trabalho e melhore a visibilidade das páginas associadas.

  • Melhorar o guia para novos redatores técnicos:

    • Expandir a estrutura da documentação.

Semana 2 (9 a 15 de setembro)

  • Trabalhe na priorização de documentação técnica:

    • Avalie o quadro de trabalho da documentação; encontre exemplos de boas descrições e priorização de tarefas.
    • Estude as tendências e anote dificuldades comuns.
    • Use as informações e os exemplos para documentar os padrões de priorização.

Semana 3 (16 a 22 de setembro)

  • Crie a seguinte documentação adicional para redatores técnicos:

    • Uma lista de verificação para ajudar a analisar a documentação técnica antes de publicar.
    • Formas de coletar conteúdo de maneira eficaz para diferentes gêneros de documentação.

Semana 4 (23 a 29 de setembro)

  • Adicione informações sobre escrita nos gêneros mais comuns da MediaWiki a modelos e sugestões de documentação técnica:

    • Documente as práticas recomendadas no MediaWiki para escrever guias do usuário, guias de início rápido, READMEs, notas de versão e instruções.

  • Acrescente orientações para melhorar a maturidade da comunicação técnica. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Semana 5 (30 de setembro a 6 de outubro)

  • Melhore a documentação para integrar novos colaboradores:

    • Atualize a página: Tarefas da documentação técnica para hackathons. (Pendentes: adicione tarefas adequadas a esta página durante todo o período do projeto)

  • Construa um centro de redação técnica

    • Crie uma página de destino com links para páginas e recursos úteis.
    • Adicione os links necessários para as páginas novas e existentes para facilitar a navegação entre elas.

Semana 6 (de 7 a 13 de outubro)

  • Crie os seguintes documentos sobre como fazer vídeos para o MediaWiki:

    • Um guia rápido sobre como criar um screencast geral para o projeto do Screencast.
    • Modelos para: tutoriais sobre como usar um software/ferramenta, tutoriais sobre o desenvolvimento de novas ferramentas.

  • Crie uma lista de ideias de screencast para o MediaWiki.

Semana 7 (14 a 20 de outubro)

  • Trabalhe no vídeo ""Introduction to Phabricator":

    • Use o modelo (criado na semana anterior) para redigir um script.
    • Estime a eficiência do modelo e faça melhorias se necessário.
    • Receba feedback e finalize o rascunho.

Semana 8 (de 21 a 27 de outubro)

  • Publique o vídeo “Introduction to Phabricator”:

    • Selecione e instale o software.
    • Configure o ambiente e crie o screencast.
    • Anote os problemas encontrados e as soluções.

Semana 9 (28 de outubro a 3 de novembro)

  • Trabalhe para melhorar a documentação do projeto do Screencast:

    • Examine a estrutura e discuta as necessidades de alterações.
    • Revise os softwares mencionados.
    • Pesquise e atualize a lista de softwares.

Semana 10 (4 a 10 de novembro)

  • Continue para melhorar a documentação do projeto do Screencast:

    • Avaliar e melhorar o tutorial e os scripts.
    • Consulte a galeria de screencasts.

Semana 11 (11 a 17 de novembro)

  • Conclua o trabalho na documentação do projeto do Screencast:

    • Encontre e adicione vídeos mais recentes à galeria.
    • Faça as mudanças estruturais necessárias.

Semana 12 (18 a 24 de novembro)

  • Trabalhe nas tarefas pendentes.

  • Elabore o relatório final:

    • Consulte os relatórios quinzenais/diários e colete as informações necessárias.
    • Planeje a estrutura do relatório e escreva um rascunho.
    • Melhorar e finalizar o rascunho com base no feedback do mentor.

Semana 13 (25 a 29 de novembro)

  • Enviar o relatório final e a avaliação do mentor.

6. Monitoramento do progresso

As atualizações diárias de progresso serão comunicadas aos meus mentores no Zulip. A comunidade do Wikimedia pode acompanhar meu progresso pelo Phabricator ou pelos relatórios quinzenais do projeto.

7. Outros compromissos

Sou estudante universitário em tempo integral, e meu semestre acadêmico se sobrepõe ao cronograma da temporada de documentos. Por isso, meus compromissos incluem provas de faculdade.

Primeiro exame interno: de 18 a 24 de agosto

Segundo exame interno: de 29 de setembro a 6 de outubro

Exame de fim de semestre: de 11 a 30 de novembro

Também pretendo participar da minha primeira conferência pública, a PyCon India, de 12 a 15 de outubro, graças à localização favorável deste ano. Acredito que seria uma ótima oportunidade para conhecer novas pessoas e ter conversas interessantes.

Para gerenciar esses compromissos, o cronograma provisório contém tarefas menos pesadas nas semanas correspondentes. Pretendo concluir no máximo 20 créditos principais no segundo semestre para ter tempo suficiente para desenvolver documentos. (Um estudante normal conclui 25 créditos em média por semestre)