Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- La Fundación Wikimedia
- Escritor técnico:
- Pavithra Eswaramoorthy
- Nombre del proyecto:
- Mejoramos la documentación para los documentalistas y camarógrafos técnicos de Wikimedia
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
1. Acerca de mí
Me presentaron el software de código abierto hace unos meses y casi de inmediato me sentí abrumada por su alcance ilimitado. Después de enfrentar los miles de millones de proyectos, aprendí sobre iniciativas de código abierto, como Google Summer of Code y Solidario. Google Season of Docs parecía interesante y las ideas de proyectos de The Wikimedia Foundation despertó mi curiosidad, así que comencé a explorar más.
Hasta ahora, mi camino ha sido emocionante y confuso, y está lleno de preguntas como "¡Espera, qué?", "Ahh, entiendo!" y "¿Debería comentar esto?". La comunidad de Wikimedia me sirvió de apoyo en cada paso. Todos los días aprendí algo nuevo, desde editar páginas hasta crear extensiones.
Como era de esperar, el proceso de aplicación fue mi puerta de enlace a la comunidad de código abierto. Esta propuesta está inspirada en mis propias experiencias como principiante.
2. Proyecto
2.1. Contorno
El objetivo de este proyecto es mejorar la documentación para escritores técnicos y posibles camarógrafos en Wikimedia. Un conjunto maduro de pautas de documentación técnica ayudaría a fomentar una mejor documentación general, y las referencias para crear presentaciones en pantalla permitirían una demostración eficaz de funciones de software. La documentación existente en estas áreas puede ampliarse para brindar una mejor asistencia tanto a los novatos como a los colaboradores experimentados. Se adoptará un enfoque gradual para desarrollar esta red de recursos útiles.
2.2. Entregas
T197006 [https://phabricator.wikimedia.org/T197006] - Mejora la documentación para los documentalistas de Wikimedia:
- Agrega sugerencias y ejemplos a la documentación o a 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 de usuario, instructivos, 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 priorizar la documentación técnica. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
- Diseñar una estrategia de recopilación de contenido para diferentes géneros de documentación
- Diseñar 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.
- Expande la estructura de la documentación para los nuevos escritores técnicos. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
- Crear una lista de tareas de documentación técnica adecuadas para hackatones. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
- Crear un centro para el escritor técnico que apunte a recursos útiles
Mejora la documentación de los camarógrafos de MediaWiki:
- Crea una guía del usuario rápida para hacer una presentación en pantalla general.
- Diseña plantillas de presentación en pantalla específicas de MediaWiki para instructivos y explicaciones.
T214522 [https://phabricator.wikimedia.org/T214522]- Crea una presentación en pantalla de “Introduction to Phabricator”.
2.3. Estirar objetivo
- Vuelve a verificar el contenido y actualiza la documentación de WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)
3. Mentores
Zulip será el medio principal de comunicación con mis mentores. Los canales de IRC y el correo electrónico de Wikimedia se usarán para los debates con la comunidad. Los debates sobre tareas específicas se llevarán a cabo en la sección de comentarios de las tareas de Phabricator.
4. Discusión
En términos generales, este proyecto se divide en dos fases:
(i) Mejorar los recursos existentes para los escritores técnicos de Wikimedia
(ii) Crear plantillas útiles para potenciales camarógrafos
(i) Mejorar los recursos existentes para los escritores técnicos de Wikimedia
En el pasado, se llevaron a cabo varias iniciativas para mejorar la documentación de MediaWiki con distintos 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 e só, una pasante de Solidario 2018: https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:
“La guía de estilo de MediaWiki dista mucho de ser perfecta, especialmente porque depende demasiado de referencias externas sin resaltar las prácticas que considera mejores. Lamentablemente, este es un problema que no se limita únicamente a MediaWiki, ya que aparece en otra documentación, como las prácticas recomendadas de Translation. Los escritores terminan sin recursos buenos y fiables para hacer su trabajo, lo que genera dificultades para establecer un público objetivo y un estilo adecuado de redacción. Además, los usuarios, especialmente los nuevos, pueden tener problemas para comprender nuevos conceptos y procesos”.
T197006 [https://phabricator.wikimedia.org/T197006] también aclara ciertas áreas de la documentación de escritura técnica que necesitan mejoras. Claramente, Documentation/Style_guide es el lugar para comenzar.
Una vez que tengamos una guía de estilo más adecuada, se planificará el siguiente conjunto de documentos para guiar a los escritores técnicos por las diferentes etapas de la redacción técnica. Los documentos deben ser aptos para principiantes y, al mismo tiempo, deben proporcionar toda la información necesaria para que los redactores puedan consultarlos.
La etapa de preparación es probablemente la más importante, ya que sienta las bases sobre las que se crea el documento. Para ayudar a los escritores técnicos en esta etapa, se desarrollan documentos de referencia en los que se describen algunas formas eficaces de recopilar información relevante y sugerencias sobre cómo estructurar esta información mediante plantillas.
Luego, viene la etapa de escritura. Los escritores reciben ejemplos de un buen trabajo para establecer automáticamente las expectativas. Además, se crea una lista de tareas con un conjunto de criterios básicos que todos los documentos deben seguir. Esto ayudará a los escritores a revisar sus documentos antes de publicarlos.
Incluso con estos documentos, los nuevos escritores técnicos necesitarán ayuda adicional, y debemos entregársela. La guía para nuevos escritores técnicos es refinada y una lista de tareas adecuadas para los hackatones se selecciona en función del nivel de dificultad.
Por último, un documento para comprender el proceso de administración y mantenimiento de la documentación: la 'priorización de la documentación técnica' se prueba y mejora.
Al final de esta fase, se establecerá un centro de guías, recursos, ejemplos, sugerencias y plantillas de redacción técnica para respaldar la guía de estilo de la documentación.
(ii) Crear plantillas útiles para potenciales camarógrafos
“Una de las formas más difíciles de aprender sobre cualquier tema que incluya gráficos es leyendo texto sin formato. Imagina también lo que sucede si tu manual hace referencia a la versión incorrecta del software. Con manuales de solo texto, a menudo es 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 pistas que normalmente usaríamos.
Quizás la mejor manera de aprender es cuando hay un experto que se sienta a tu lado. La presentación en pantalla se sitúa entre los gráficos estáticos y la presencia de un experto al alcance de la mano. Obtenemos una demostración visual y conmovedora con una voz amigable, también podemos incluir anotaciones de texto en la pantalla y animaciones. Una ventaja de las presentaciones en pantalla sobre las de un experto es que se pueden volver a reproducir cada hora todos los días.
También podemos agregar subtítulos traducidos a una presentación en pantalla para que los hablantes no nativos puedan verlos 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, cómo escribir extensiones, cómo usar Gerrit y mucho más.
Al igual que las plantillas para documentos, tener una plantilla estándar para presentaciones en pantalla promueve la uniformidad, lo que mejora la experiencia del usuario. También les brinda a los potenciales camarógrafos un marco para comenzar. Por lo tanto, se desarrolla una guía rápida del usuario seguida de plantillas para crear videos introductorios y tutoriales. Los documentos incluyen puntos sobre la profundidad de los conceptos que se tratarán y algunas ideas de presentación en pantalla para MediaWiki.
La mejor manera de probar la plantilla anterior y prepararse para el objetivo más amplio es crear una presentación en pantalla con las herramientas y las plantillas. Por lo tanto, se crea una presentación en pantalla "Introduction to Phabricator" que cubre los conceptos básicos del uso de Phabricator. Este proceso también destacaría las áreas que necesitan debate.
Por último, revisa y actualiza WikiProject Screencast, la principal fuente de referencia para los camarógrafos de Wikimedia.
5. Cronograma tentativo
Período de vinculación con la comunidad (del 1 de agosto al 1 de septiembre)
- analizar el proyecto en detalle con mis mentores.
Analiza lo siguiente:
- Con qué frecuencia se deben revisar las tareas.
- Comparte programas y define un flujo de trabajo semanal o diario.
- Herramientas y recursos que se pueden usar.
- Informes de proyectos quincenales y diarios
Crea las tareas y subtareas necesarias en Phabricator.
Crear borradores para compensar los compromisos personales durante la fase de desarrollo de documentos
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 de MediaWiki.
- Incluye ejemplos de un buen trabajo y mejora la visibilidad de las páginas asociadas.
Mejora la guía para escritores técnicos nuevos:
- Expandir la estructura de la documentación
Semana 2 (del 9 al 15 de septiembre)
Trabajo en la priorización de la documentación técnica:
- Evaluar la mesa de trabajo de documentación; encontrar ejemplos de buenas descripciones y priorización de tareas.
- Estudia las tendencias y toma nota de las dificultades más 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 ayudar a revisar la documentación técnica antes de la publicación.
- 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 la escritura 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 del 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)
Mejorar la documentación para incorporar nuevos colaboradores:
- Actualización de la página: Tareas de documentación técnica para hackatones. (Pendientes: Agrega las tareas adecuadas a esta página durante todo el período del proyecto)
Construye 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 nueva y existente 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:
- Guía rápida del usuario sobre cómo crear una presentación en pantalla general que apunte al proyecto Screencast.
- Plantillas para: Explicaciones sobre el uso de un software/herramienta; tutoriales sobre desarrollo de nuevas herramientas.
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 crear un borrador de una secuencia de comandos.
- Estima la eficiencia de la plantilla y mejórala si es necesario.
- Obtener comentarios y finalizar el borrador
Semana 8 (del 21 al 27 de octubre)
Publica el video “Introduction to Phabricator”:
- Selecciona el software y, luego, instálalo.
- 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 Screencast:
- Examina la estructura y analiza si es necesario realizar cambios.
- Revisa los software mencionados.
- Investiga y actualiza la lista de software.
Semana 10 (del 4 al 10 de noviembre)
Sigue mejorando la documentación del proyecto de Screencast:
- 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 Screencast:
- Busca videos nuevos y agrégalos 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 necesaria.
- Planifica la estructura del informe y redacta un borrador.
- Mejorar y finalizar el borrador en función de los comentarios de los mentores.
Semana 13 (del 25 al 29 de noviembre)
- Enviar 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 seguir mi progreso a través de Phabricator o los informes de proyecto quincenales.
7. Otros compromisos
Soy estudiante universitario de tiempo completo, y mi semestre académico de otoño coincide con el cronograma de la temporada de Documentos. Por lo tanto, mis compromisos incluyen los 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 pienso 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 gente nueva y tener conversaciones interesantes.
Para gestionar estos compromisos, el cronograma tentativo contiene tareas menos pesadas en las semanas correspondientes. Tengo la intención de completar no más de 20 créditos principales en el semestre de otoño a fin de tener tiempo suficiente para el desarrollo de documentos. (Un estudiante normal completa un promedio de 25 créditos por semestre)