O projeto da Fundação Wikimedia

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:
The Wikimedia Foundation
Redator técnico:
Pavithra Eswaramoorthy
Nome do projeto:
Como melhorar a documentação para documentaristas e videomakers técnicos da Wikimedia
Duração do projeto:
Duração padrão (três meses)

Project description

1. Sobre mim

Conheci o software de código aberto há alguns meses e quase imediatamente me senti sobrecarregado pelo escopo ilimitado dele. Com dificuldade para avançar entre os vários projetos, aprendi sobre iniciativas de código aberto, como o Google Summer of Code e o Outreachy. O Google Season of Docs parecia interessante, e as ideias de projeto da Fundação Wikimedia despertaram minha curiosidade, então comecei a explorar mais.

Minha jornada até agora foi ao mesmo tempo empolgante e confusa, cheia de “espera aí”, “ah, entendi” e “Devo comentar sobre isso?”. A comunidade da Wikimedia me apoiou em cada etapa. Desde a edição de páginas até a criação de extensões, aprendo algo novo todos os dias.

Como esperado, o processo de inscrição serviu como 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

O objetivo deste projeto é melhorar a documentação para redatores técnicos e possíveis videomakers na Wikimedia. Um conjunto maduro de diretrizes de documentação técnica ajudaria a melhorar a documentação geral, e as referências para a criação de screencasts permitiriam a demonstração eficaz dos recursos do software. A documentação existente nessas áreas pode ser estendida para oferecer melhor suporte a colaboradores experientes e iniciantes. Uma abordagem incremental será adotada para desenvolver essa rede de recursos úteis.

2.2. Resultados

  • T197006 [https://phabricator.wikimedia.org/T197006] - Melhoria na documentação para documentaristas da Wikimedia:

    • Adicionar dicas e exemplos à documentação/guia de 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, tutoriais, guias de início rápido, notas da versão e READMEs. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Teste e melhore as diretrizes de priorização da documentação técnica. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Crie uma estratégia de coleta de conteúdo para diferentes tipos de documentação.
    • Desenvolva uma estratégia de comunicação e colaboração para a documentação do MediaWiki.
    • Criar uma lista de verificação para os redatores revisarem os documentos antes de publicarem.
    • Expandir a estrutura de documentação para novos redatores técnicos. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Crie uma lista de tarefas de documentação técnica adequadas para hackathons. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Crie um hub de redatores técnicos que indique recursos úteis.

  • Melhoria na documentação para cinegrafistas do MediaWiki:

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

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

2.3. Meta ambiciosa

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

3. Mentores

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

4. Discussão

Esse projeto é dividido em duas fases:

(i) Melhorar os recursos atuais para os redatores técnicos da Wikimedia.

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

(i) Melhorar os recursos atuais para os redatores técnicos da 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

Com esses esforços, podemos entender que um conjunto melhor de recursos para redatores técnicos terá um impacto direto nos documentos gerados por eles.

O snippet a seguir é do relatório quinzenal de uma estagiária do Outreachy 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 ele considera as melhores. Infelizmente, esse problema não está restrito apenas ao MediaWiki, já que aparece em outras documentações, como as práticas recomendadas de tradução. Os redatores 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, principalmente os novos, podem ter problemas para entender novos conceitos e processos.”

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

Assim que tivermos um guia de estilo melhor, o próximo conjunto de documentos será planejado para orientar os redatores técnicos pelas diferentes fases da redação técnica. Os documentos precisam ser fáceis de usar para iniciantes e, ao mesmo tempo, fornecer todas as informações necessárias para que os redatores possam consultar.

A fase de preparação é possivelmente a mais importante, porque é a base para a criação do documento. Para ajudar os redatores técnicos nessa fase, os documentos de referência foram desenvolvidos para descrever algumas maneiras eficazes de coletar informações relevantes e dicas sobre como estruturar essas informações usando modelos.

Depois vem a fase de escrita. Os redatores recebem exemplos de bons trabalhos para elevar automaticamente o nível. Além disso, uma lista de verificação é criada com um conjunto de critérios básicos que todos os documentos precisam seguir. Isso ajuda os redatores a revisar os documentos antes da publicação.

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

Finalmente, um documento para compreender o processo de gerenciamento e manutenção de documentação - a "Priorização da documentação técnica" é testada e aprimorada.

Ao final dessa fase, um hub de guias, recursos, exemplos, sugestões e modelos de redação técnica será estabelecido para apoiar 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 referir à versão errada do software. Com manuais somente de texto, muitas vezes fica impossível recriar uma série de ações quando os menus e a redação do aplicativo mudam, já que não temos todas as dicas que normalmente usamos.

Talvez a melhor maneira de aprender seja quando você tem um especialista sentado ao seu lado. Os screencasts ficam entre os gráficos estáticos e a presença de um especialista. Temos uma demonstração visual e animada com uma voz amigável. Também podemos ter anotações de texto na tela e animações. Uma vantagem dos screencasts em relação a um especialista é que eles podem ser assistidos a qualquer hora do dia.

Também podemos adicionar legendas traduzidas a um screencast para que possam ser vistas por pessoas que não falam o idioma nativo ou substituir a faixa de áudio por outros idiomas."

No snippet acima de ""The Screencasting Handbook"" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald explica a importância dos screencasts. Ele 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 a possíveis cinegrafistas um framework 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 dicas 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 a nova meta é criar um screencast usando as ferramentas e os modelos. Portanto, um screencast "Introdução ao Phabricator" foi criado para abordar os conceitos básicos de uso do Phabricator. Esse processo também destaca as áreas que precisam de discussão.

Por fim, a fonte central de referência para os cinegrafistas da Wikimedia, o WikiProject Screencast, foi revisado e atualizado.

5. Cronograma provisório

Período de vinculação à comunidade (1º de agosto a 1º de setembro)

  • Analisar o projeto em detalhes com meus mentores.

  • Discutir sobre:

    • Com que frequência as tarefas precisam ser analisadas.
    • Compartilhe horários e decida sobre um fluxo de trabalho semanal/diário.
    • Ferramentas e recursos que podem ser usados.
    • Relatórios de projeto diários e quinzenais.

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

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

Semana 1 (2 a 8 de setembro)

  • Melhoria na documentação/Style_guide:

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

  • Melhorar o guia para novos escritores técnicos:

    • Expandir a estrutura da documentação.

Semana 2 (9 a 15 de setembro)

  • Trabalhar na priorização da documentação técnica:

    • Avalie a prancheta de trabalho de documentação e encontre exemplos de boas descrições de tarefas e priorização.
    • Estude as tendências e anote as dificuldades comuns.
    • Use as informações e 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 revisar a documentação técnica antes da publicação.
    • Formas de coletar conteúdo de forma eficaz para diferentes gêneros de documentação.

Semana 4 (23 a 29 de setembro)

  • Adicione informações sobre como escrever nos gêneros mais comuns do MediaWiki aos 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 lançamento e tutoriais.

  • Adicione instruçõ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 a integração de novos colaboradores:

    • Atualize a página: tarefas de documentação técnica para hackatons. (Tarefa: adicione tarefas adequadas a esta página durante o período do projeto)

  • Criar um hub para redatores técnicos

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

Semana 6 (7 a 13 de outubro)

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

    • Um guia rápido do usuário sobre "como criar um screencast geral" que aponta para o projeto do Screencast.
    • Modelos para: tutoriais sobre como usar um software/ferramenta e tutoriais sobre como desenvolver novas ferramentas.

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

Semana 7 (14 a 20 de outubro)

  • Assista ao vídeo "Introdução ao Phabricator":

    • Use o modelo (criado na semana anterior) para fazer o rascunho de um roteiro.
    • Avalie a eficiência do modelo e melhore-o, se necessário.
    • Receber feedback e finalizar o rascunho.

Semana 8 (21 a 27 de outubro)

  • Publique o vídeo "Introdução ao 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 de screencast:

    • Examine a estrutura e discuta se é necessário fazer mudanças.
    • Analise os softwares mencionados.
    • Pesquise e atualize a lista de softwares.

Semana 10 (4 a 10 de novembro)

  • Continue aprimorando a documentação do projeto do Screencast:

    • Avalie e melhore o tutorial e os scripts.
    • Analise 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)

  • Trabalhar em tarefas pendentes.

  • Escreva o relatório final:

    • Consulte os relatórios semanais/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)

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

6. Acompanhamento do progresso

O progresso diário será comunicado aos meus mentores pelo Zulip. A comunidade 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 de outono acadêmico se sobrepõe à programação da Temporada dos Documentos. Por isso, meus compromissos incluem exames universitários.

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, a linha do tempo provisória contém tarefas menos importantes nas semanas correspondentes. Pretendo concluir no máximo 20 créditos obrigatórios no semestre de outono para ter tempo suficiente para o desenvolvimento de documentos. (um estudante regular conclui 25 créditos em média por semestre)