El proyecto de la Fundación Wikimedia

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.

Resumen del proyecto

Organización de código abierto:
Wikimedia Foundation
Escritor técnico:
Pavithra Eswaramoorthy
Nombre del proyecto:
Mejora la documentación para los documentalistas y videógrafos técnicos de Wikimedia
Duración del proyecto:
Duración estándar (3 meses)

Project description

1. Acerca de mí

Hace algunos meses, me presentaron el software de código abierto y, casi de inmediato, me sentí abrumado por su alcance ilimitado. Mientras me esforzaba por avanzar entre los miles de proyectos, aprendí sobre iniciativas de código abierto como Google Summer of Code y Outreachy. La Temporada de Documentos de Google me pareció interesante y las ideas de proyectos de la Wikimedia Foundation despertaron mi curiosidad, así que comencé a explorar más.

Hasta ahora, mi recorrido ha sido emocionante y confuso en partes iguales, lleno de preguntas como “¿Espera, qué?”, “Ahhh, ya entiendo” y “¿Debo comentar esto?”. La comunidad de Wikimedia me ha brindado apoyo en cada paso. Desde la edición de páginas hasta la creación de extensiones, aprendí algo nuevo todos los días.

Como esperaba, el proceso de postulación me sirvió como puerta de entrada a la comunidad de código abierto. Esta propuesta se inspira en mis propias experiencias como principiante.

2. Proyecto

2.1. Contorno

El objetivo de este proyecto es mejorar la documentación para los redactores técnicos y los posibles videógrafos de Wikimedia. Un conjunto maduro de lineamientos de documentación técnica ayudaría a mejorar la documentación general, y las referencias para crear presentaciones en pantalla permitirían demostrar las funciones del software de manera eficaz. La documentación existente en estas áreas se puede ampliar para brindar una mejor asistencia a los colaboradores nuevos y experimentados. Se adoptará un enfoque incremental para desarrollar esta red de recursos útiles.

2.2. Resultados

  • T197006 [https://phabricator.wikimedia.org/T197006]: Mejora la documentación para los documentalistas de Wikimedia:

    • Agrega sugerencias y ejemplos a la documentación o la guía de estilo. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Agrega información específica de MediaWiki a determinados géneros en plantillas y sugerencias de documentación técnica: guías del usuario, guías prácticas, guías de inicio rápido, notas de la versión y archivos README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Prueba y mejora los lineamientos para la priorización de la documentación técnica. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Diseña una estrategia de recopilación de contenido para diferentes géneros de documentación.
    • Diseña una estrategia de comunicación y colaboración para la documentación de MediaWiki.
    • Crea una lista de tareas con la que los escritores puedan revisar sus documentos antes de publicarlos.
    • Expandir la estructura de documentación para los nuevos redactores técnicos [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Crea una lista de tareas de documentación técnica adecuadas para hackathons. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Crea un centro para escritores técnicos que dirija a los usuarios a recursos útiles.

  • Se mejoró la documentación para los camarógrafos de MediaWiki:

    • Crea una guía rápida para el usuario para crear una presentación en pantalla general.
    • Diseña plantillas de presentación en pantalla específicas de MediaWiki para explicaciones e instructivos.

  • T214522 [https://phabricator.wikimedia.org/T214522]- Crea una presentación en pantalla “Introduction to Phabricator”.

2.3. Objetivo adicional

  • Vuelve a revisar el contenido y actualiza la documentación de la presentación en pantalla de WikiProject. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentores

Zulip será el principal modo de comunicación con mis mentores. Los canales de IRC y el correo electrónico de Wikimedia se usarán para las conversaciones con la comunidad. Los debates sobre tareas específicas tendrán lugar en la sección de comentarios de las tareas de Phabricator.

4. Debate

Este proyecto se divide en dos fases:

(i) Mejorar los recursos existentes para los escritores técnicos de Wikimedia

(ii) Crear plantillas útiles para posibles camarógrafos.

(i) Mejorar los recursos existentes para los redactores técnicos de Wikimedia

En el pasado, hubo varias iniciativas para mejorar la documentación de MediaWiki con diferentes grados de éxito. A continuación, te mostramos algunas de ellas:

  • 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 de estos esfuerzos, podemos comprender que un mejor conjunto de recursos para los redactores técnicos tendrá un impacto directo en los documentos que generen.

El siguiente es un fragmento del informe quincenal de Anna, una pasante de Outreachy 2018, https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

“La guía de estilo de MediaWiki está lejos de ser perfecta, en especial porque depende demasiado de referencias externas sin destacar qué prácticas considera las mejores. Lamentablemente, este es un problema que no se limita solo a MediaWiki, ya que aparece en otra documentación, como las prácticas recomendadas de Translation. Los escritores terminan sin recursos buenos y confiables para hacer su trabajo, lo que genera dificultades para establecer un público objetivo y un estilo de escritura adecuado. Además, los usuarios, en especial los nuevos, pueden tener problemas para comprender los conceptos y procesos nuevos”.

T197006 [https://phabricator.wikimedia.org/T197006] también arroja luz sobre ciertas áreas de la documentación de redacción técnica que necesitan mejoras. Claramente, Documentation/Style_guide es el punto de partida.

Una vez que tengamos una mejor guía de estilo, el siguiente conjunto de documentos se planificará para guiar a los redactores técnicos a través de las diferentes etapas de la escritura técnica. La documentación debe ser fácil de usar para principiantes y, al mismo tiempo, proporcionar toda la información necesaria para que los escritores la consulten.

La etapa de preparación es posiblemente la más importante, ya que sienta las bases sobre las que se construye el documento. Para ayudar a los escritores técnicos en esta etapa, se desarrollan documentos de referencia que describen algunas formas eficaces de recopilar información relevante y consejos sobre cómo estructurar esta información mediante plantillas.

Luego viene la etapa de escritura. Los redactores reciben ejemplos de buen trabajo para establecer automáticamente las expectativas. Además, se crea una lista de tareas con un conjunto de criterios básicos que deben seguir todos los documentos, lo que ayudará a los escritores a revisar sus documentos antes de publicarlos.

Incluso con estos documentos, los nuevos redactores técnicos necesitarán ayuda adicional, y debemos brindarles esa ayuda. Se perfeccionó la guía para nuevos escritores técnicos y se seleccionó una lista de tareas adecuadas para hackathons en función del nivel de dificultad.

Por último, se prueba y mejora el documento “Priorización de la documentación técnica” para comprender el proceso de administración y mantenimiento de la documentación.

Al final de esta fase, se establecerá un centro de guías, recursos, ejemplos, sugerencias y plantillas de redacción técnica que respaldarán la guía de estilo de la documentación.

ii) Crear plantillas útiles para posibles camarógrafos.

“Una de las formas más difíciles de aprender algo que involucre gráficos es leer texto sin formato. Imagina también lo que sucede si tu manual hace referencia a la versión incorrecta del software: con manuales solo de texto, a menudo, resulta imposible recrear una serie de acciones cuando los menús y la redacción de la aplicación cambian, ya que nos faltan todas las indicaciones que normalmente utilizaríamos.

Quizás la mejor forma de aprender es cuando tienes a un experto sentado a tu lado. Las presentaciones en pantalla se encuentran entre los gráficos estáticos y tener un experto a mano. Obtenemos una demostración visual y de movimiento con una voz amigable. También podemos tener anotaciones de texto en la pantalla y animaciones. Una ventaja de las presentaciones en pantalla sobre un experto es que se pueden volver a reproducir a voluntad, todas las horas del día.

También podemos agregar subtítulos traducidos a una presentación en pantalla para que los usuarios que no hablan el idioma nativo puedan verlas o reemplazar la pista de audio por idiomas alternativos”.

En el fragmento anterior de ""The Screencasting Handbook"" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald explica la importancia de las presentaciones en pantalla. Podría ser especialmente útil para instructivos sobre la configuración del entorno de desarrollo de MediaWiki, la escritura de extensiones, el uso de Gerrit y mucho más.

Al igual que con las plantillas de documentos, tener una plantilla estándar para las presentaciones en pantalla promueve la uniformidad y, de esta manera, mejora la experiencia del usuario. También proporciona a los posibles videógrafos un marco de trabajo para comenzar. Por lo tanto, se desarrolla una guía rápida para el usuario seguida de plantillas para crear videos introductorios y de instructivos. Los documentos incluyen punteros sobre la profundidad de los conceptos que se abordarán y algunas ideas de instructivos multimedia para MediaWiki.

La mejor manera de probar la plantilla anterior y prepararte para el objetivo de ampliación es crear una presentación en pantalla con las herramientas y plantillas. Por lo tanto, se crea una presentación en pantalla “Introducción a Phabricator” que abarca los conceptos básicos del uso de Phabricator. Este proceso también destacaría las áreas que necesitan debate.

Por último, se revisa y actualiza la fuente de referencia central para los videógrafos de Wikimedia: WikiProject Screencast.

5. Cronograma tentativo

Período de unión de la comunidad (del 1 de agosto al 1 de septiembre)

  • Analizar el proyecto en detalle con mis mentores

  • Analiza lo siguiente:

    • La frecuencia con la que se deben revisar las tareas
    • Comparte programas y decide un flujo de trabajo semanal o diario.
    • Herramientas y recursos que se pueden usar.
    • Informes del proyecto quincenales y diarios.

  • Crea las tareas y subtareas necesarias en Phabricator.

  • Crea borradores para compensar los compromisos personales durante la fase de desarrollo del documento.

Semana 1 (del 2 al 8 de septiembre)

  • Mejora la documentación/guía de estilo:

    • Cambia el enfoque principal para ilustrar las prácticas recomendadas y los estándares en MediaWiki.
    • Incluye ejemplos de buen trabajo y mejora la visibilidad de las páginas asociadas.

  • Mejora la guía para escritores técnicos nuevos:

    • Expande la estructura de la documentación.

Semana 2 (del 9 al 15 de septiembre)

  • Trabaja en la priorización de la documentación técnica:

    • Evalúa el panel de trabajo de documentación y busca ejemplos de buenas descripciones de tareas y priorización.
    • Estudia las tendencias y anota las dificultades comunes.
    • Usa la información y los ejemplos para documentar los estándares de priorización.

Semana 3 (del 16 al 22 de septiembre)

  • Crea la siguiente documentación adicional para escritores técnicos:

    • Una lista de tareas para revisar la documentación técnica antes de publicarla.
    • Formas de recopilar contenido de manera eficaz para diferentes géneros de documentación.

Semana 4 (del 23 al 29 de septiembre)

  • Agrega información sobre cómo escribir en los géneros de MediaWiki más comunes a las plantillas y sugerencias de documentación técnica:

    • Documenta las prácticas recomendadas en MediaWiki para escribir guías de usuario, guías de inicio rápido, archivos README, notas de la versión e instructivos.

  • Agrega instrucciones para mejorar la madurez de la comunicación técnica. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Semana 5 (del 30 de septiembre al 6 de octubre)

  • Mejora la documentación para incorporar nuevos colaboradores:

    • Actualización de la página: Tareas de documentación técnica para hackathons. (Tarea pendiente: Agrega tareas adecuadas a esta página durante el período del proyecto)

  • Crea un centro para escritores técnicos

    • Crea una página de destino con vínculos a páginas y recursos útiles.
    • Agrega los vínculos necesarios a las páginas nuevas y existentes para facilitar la navegación entre ellas.

Semana 6 (del 7 al 13 de octubre)

  • Crea los siguientes documentos sobre cómo crear videos para MediaWiki:

    • Una guía rápida para el usuario sobre "cómo crear una presentación en pantalla general" que dirige al proyecto de presentación en pantalla
    • Plantillas para instructivos sobre el uso de un software o una herramienta, y para desarrollar herramientas nuevas

  • Crea una lista de ideas de presentaciones en pantalla para MediaWiki.

Semana 7 (del 14 al 20 de octubre)

  • Trabaja en el video ""Introduction to Phabricator" (Introducción a Phabricator):

    • Usa la plantilla (creada la semana anterior) para escribir un borrador de un guion.
    • Estima la eficiencia de la plantilla y mejorala si es necesario.
    • Obtén comentarios y finaliza el borrador.

Semana 8 (del 21 al 27 de octubre)

  • Publica el video “Introducción a Phabricator”:

    • Selecciona e instala el software.
    • Configura el entorno y crea la presentación en pantalla.
    • Anota los problemas encontrados y las soluciones.

Semana 9 (del 28 de octubre al 3 de noviembre)

  • Trabaja para mejorar la documentación del proyecto de presentación en pantalla:

    • Examina la estructura y analiza si es necesario realizar cambios.
    • Revisa los softwares mencionados.
    • Investiga y actualiza la lista de softwares.

Semana 10 (del 4 al 10 de noviembre)

  • Sigue mejorando la documentación del proyecto de presentación en pantalla:

    • Evaluar y mejorar el instructivo y las secuencias de comandos
    • Revisa la galería de presentaciones en pantalla.

Semana 11 (del 11 al 17 de noviembre)

  • Completa el trabajo en la documentación del proyecto de presentación en pantalla:

    • Busca y agrega videos más recientes a la galería.
    • Realiza los cambios estructurales necesarios.

Semana 12 (del 18 al 24 de noviembre)

  • Trabaja en las tareas pendientes.

  • Escribe el informe final:

    • Consulta los informes quincenales o diarios y recopila la información requerida.
    • Planifica la estructura del informe y escribe un borrador.
    • Mejora y finaliza el borrador en función de los comentarios del mentor.

Semana 13 (del 25 al 29 de noviembre)

  • Envía el informe final y la evaluación del mentor.

6. Seguimiento del progreso

Las actualizaciones diarias del progreso se comunicarán a mis mentores a través de Zulip. La comunidad de Wikimedia puede hacer un seguimiento de mi progreso a través de Phabricator o los informes del proyecto quincenales.

7. Otros compromisos

Soy estudiante universitario de tiempo completo y mi semestre académico de otoño se superpone con el cronograma de la Temporada de Documentos. Por lo tanto, mis compromisos incluyen exámenes universitarios.

Primer examen interno: Del 18 al 24 de agosto

Segundo examen interno: Del 29 de septiembre al 6 de octubre

Examen de fin de semestre: del 11 al 30 de noviembre

También planeo asistir a mi primera conferencia pública, PyCon India, del 12 al 15 de octubre, gracias a la ubicación favorable de este año. Creo que sería una gran oportunidad para conocer a nuevas personas y tener conversaciones interesantes.

Para gestionar estos compromisos, el cronograma tentativo incluye tareas menos importantes en las semanas correspondientes. Mi intención es completar no más de 20 créditos básicos en el semestre de otoño para tener tiempo suficiente para el desarrollo de documentos. (Un estudiante regular completa 25 créditos en promedio por semestre).