Proyecto de electron

En esta página, se incluyen 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:

Electrón

Escritor técnico:

Mister Gold

Nombre del proyecto:

Flujo del instructivo de Electron

Duración del proyecto:

Duración estándar (3 meses)

Project description

RESUMEN DEL PROYECTO

Electron es una de las herramientas más populares para compilar apps de escritorio multiplataforma con JavaScript, HTML y CSS. Una colección de apps compiladas en Electron tiene casi 900 entradas, y esta lista crece de forma continua. Algunas de las herramientas para desarrolladores más populares, como Visual Studio Code, Atom, Postman, Slack y GitKraken, se compilan en Electron.

La popularidad de Electron radica en su curva de aprendizaje simple y su bajo umbral de entrada: cualquier persona que conozca la pila de JavaScript, HTML y CSS puede compilar su propia aplicación. Los enormes porcentajes de crecimiento generales exigen la creación de instructivos y guías de introducción que sean fáciles de entender y usar.

El objetivo del proyecto es brindar confianza a los creadores de aplicaciones que son nuevos en el framework de Electron y proporcionarles una experiencia coherente y optimizada para desarrollar sus propias aplicaciones de Electron desde cero.

Problemas del proyecto

A continuación, se incluye una lista de los problemas más importantes relacionados con la documentación de los instructivos de Electron: 1. Punto de partida poco claro e información introductoria no intuitiva sobre los pasos de desarrollo de la aplicación 2. Información dispersa y redundante relacionada con el proceso de desarrollo de la aplicación 3. Piezas desorganizadas de instrucciones de “inicio” que sirven de guía y no tienen una única fuente de información

PROPUESTA DEL PROYECTO

Según el objetivo del proyecto y los problemas descritos anteriormente, la siguiente es una lista de las mejoras propuestas: 1. Actualiza las guías existentes. Para que los primeros pasos sean fluidos y coherentes, se deben actualizar los siguientes documentos con un cambio gradual de lo simple a lo más complejo: - Entorno de desarrollador - Cómo escribir tu primera app de Electron - Cómo agregar funciones a tu app (crea una página de resumen) - Empaquetado y distribución de apps 2. Reestructura el directorio de documentación. Para mostrarles a los nuevos desarrolladores lo que es esencial para comenzar y lo que se puede considerar como pasos adicionales, la página de documentos debe tener una división visual y contextual de los pasos para que la primera aplicación funcione lo más rápido posible. La reestructuración también incluye orientación sobre los posibles próximos pasos. 3. Organizar y unificar la documentación de desarrollo de aplicaciones Todas las funciones deben tener un conjunto unificado de instrucciones para instalarlas o habilitarlas, comenzar a usarlas rápidamente, trabajar con una app después del primer lanzamiento y distribuirla. 4. Se incluye el repositorio electron-api-demos en la documentación. El repositorio electron-api-demos contiene un conjunto de ejemplos que muestran cómo agregar funciones a tu aplicación de Electron. Esta información se debe incluir en la guía para agregar funciones a tu app para que sea coherente con una estrategia de contenido de una sola fuente de confianza. 5. Se integraron ejemplos de Electron Fiddle en la documentación. Este paso facilitará que los desarrolladores nuevos vean cómo funciona un fragmento de código en particular sin tener que repetir los pasos de forma manual. La integración incluye escribir ejemplos de código para los instructivos actualizados y agregar el botón “Launch in Fiddle” a los bloques de código.

Cronología

Período de revisión de la solicitud: Familiarízate con la comunidad y las personas con las que trabajarás. Conoce las guías y prácticas recomendadas de contribuciones de la comunidad. Realiza las primeras contribuciones. Vinculación con la comunidad: Explora la comunidad. Inspecciona el estado actual de la documentación de Electron. Identifica los puntos débiles. Semana 1: alinearte con los mentores sobre los hitos y las entregas del proyecto. Semana 2: Revisa el entorno de desarrollo y escribe las páginas de tu primera app electrónica. Semana 3: Revisa la arquitectura de aplicaciones, agrega funciones a tu app, y las páginas de distribución y empaquetado de apps. Crea una página de resumen con una lista de las funciones que se pueden agregar a la app. Semana 4: Reestructura el directorio de documentación. Semana 5: Prepara una plantilla de cómo se integrará electron-api-demos en la documentación principal. Semanas 6 y 7: Migra el repositorio de electron-api-demos. Semana 8: Prepara una plantilla de cómo se integrará Electron Fiddle en la documentación principal. Escribe la primera muestra. Semanas 9 y 10: Integra Electron Fiddle en la documentación principal Semana 11: Finalización de la estructura y las páginas de la documentación principal después de migrar el repositorio electron-api-demos y los ejemplos de Electron Fiddle Semana 12: Evaluación de los resultados

DESGLOSE DETALLADO DE LOS HITOS

PERÍODO DE REVISIÓN DE LA SOLICITUD La primera parte del período se dedicará a revisar los canales y el código fuente de la comunidad, y a contactar a las personas dedicadas al proyecto.

La segunda parte del período se dedicará a comprobar la cultura de contribución en general, examinar las guías de contribución y las prácticas recomendadas. Este será el momento de las primeras contribuciones para ver cómo funciona el flujo.

VINCULOS DE COMUNIDAD

Este tiempo se dedicará a un análisis más profundo de la carpeta de documentación junto con su hoja de ruta. Con esa información, será posible identificar los puntos débiles (p.ej., partes incompletas o faltantes) que se pueden mejorar. Crea solicitudes de extracción (siempre que sea posible) para cubrir las brechas.

SEMANA 1 - SEMANA 2

La primera semana se dedicará a la comunicación con los mentores para alinearse con los eventos importantes esperados y su entrega oportuna.

La segunda semana se dedicará a revisar las páginas del entorno de desarrollo y Cómo escribir tu primera app de Electron. En la página Entorno de desarrollador, se incluirá la reescritura de la descripción general general y la revisión de texto. Para la página Cómo escribir tu primera aplicación electrónica, se incluirá cómo hacer que la página sea una guía paso a paso consistente con puntos de inicio y finalización claros y la eliminación de información redundante (como dos bloques de código similares en Desarrollo electrónico en Nutshell y Prueba esta sección de ejemplo).

Entregables: Guías de introducción revisadas y fáciles de seguir para comenzar a usar aplicaciones de Electron.

SEMANA 3

Esta semana se dedicará a lo siguiente: 1. Mejoras en la página de arquitectura de aplicaciones. Esto incluye lo siguiente: - La reescritura de la información existente en la sección Procesos principales y de renderización para que sea más simple y más intuitiva para un lector por primera vez. - La adición de una representación visual de la arquitectura, cómo se conectan los procesos, cómo se comunican y su diferencia principal. Ejemplos de recursos visuales: Uno, Dos, Tres (baja calidad). 2. Unificación de la información sobre todas las funciones que puedes agregar a tu aplicación de Electron. Esto incluye volver a escribir las guías para que tengan un conjunto unificado de instrucciones sobre cómo instalar o habilitar una función, junto con un ejemplo de cómo funciona. Además, se creará una nueva página (de resumen) en la que se enumerarán todas las funciones disponibles para usar. Las instrucciones unificadas pueden verse de la siguiente manera: - Descripción general - Ejemplo: - Muestra de código - Ejemplo visual (cuando sea posible)

1. simplificación de la página Aplicación de distribución Esto incluye lo siguiente: a. fusionar el empaquetado de aplicaciones en la guía de Distribución de aplicaciones b. dividir los métodos de distribución en automático y manual c. tomar la forja electrónica como un ejemplo de distribución automática d. tomar información sobre asar de la página de empaquetado de aplicaciones y describir cómo copiar archivos fuente y crear un archivo asar como ejemplos de distribución manual #### SEMANA 4 Esta semana se dedicará a la reestructuración del directorio de documentación. It includes:

1) Dividir las guías existentes en, al menos, tres categorías: a. Guía de inicio rápido b. Aprender los conceptos básicos c. Pasos avanzados

La categoría Guías de inicio rápido contendrá los instructivos básicos (instalación, configuración y distribución) para crear una serie coherente de guías que permitan a los recién llegados comenzar desde cero. Cada guía debe contener vínculos a las guías anteriores o siguientes de la serie.

La estructura puede tener el siguiente aspecto: 1. Requisitos previos 2. Instala Electron. Crea una aplicación básica 4. Empaquetar o distribuir la aplicación

Después de completar la sección de la guía de inicio rápido, el usuario conocerá los conceptos básicos del funcionamiento de las aplicaciones de Electron y tendrá una aplicación de Electron distribuible que funcione completamente.

La categoría Aprender los conceptos básicos contendrá las guías destinadas a fortalecer los conocimientos sobre Electron y extender la aplicación creada en las secciones de Inicio rápido. Estas guías incluyen lo siguiente: - Arquitectura de aplicaciones - Cómo agregar funciones a tu app - Plantillas y CLI

La categoría Pasos avanzados contendrá guías más avanzadas para configurar y ajustar tu aplicación de Electron: - Pruebas y depuración - Accesibilidad - Seguridad - Actualizaciones

2 - Reducir la cantidad de páginas de documentación La versión actual de la documentación contiene un cierto grado de superposición de contenido y de instrucciones sin categorizar. Por ejemplo: - Instalación e instalación de Electron en la sección Cómo escribir tu primera app. - Cómo empaquetar y empaquetar tu app en un archivo dentro de Application Distribution. - Instrucciones sin clasificar en las categorías En detalle y Avanzado: Sugerencia: Mueve los siguientes documentos a GitHub y exclúyelos de la documentación principal. Estos documentos son específicos de los lineamientos de desarrollo de Electron, y el repositorio de origen es el primer lugar donde buscarlos: - Desarrollo de Electron - Desarrollo de Chromium - Desarrollo de V8 - Problemas en Electron - Parches en Electron - Solicitudes de extracción - Estructura del directorio del código fuente - Pruebas - Estilo de programación

La idea principal de la reducción es deshacerse de una cantidad abrumadora de guías disponibles, unir las piezas dispersas del rompecabezas de información y brindarles a los recién llegados una versión de la documentación de Electron más estructurada, fácil de navegar y fácil de usar.

SEMANAS 5 A 7

La semana 5 se dedicará a preparar una plantilla (una forma) de cómo se integrará electron-api-demos en la documentación principal. Esta plantilla puede verse de la siguiente manera: 1. En la documentación principal, en “Agrega funciones a tu app”, crea las categorías representadas en electron-api-demos 2. A medida que revises cada una de las categorías, transfiere los ejemplos de demostración a la documentación principal: - Las muestras de código se pueden tomar del código fuente o de la descripción de la función correspondiente en la aplicación. - Cada ejemplo transferido debe ir seguido de la descripción asociada. - Cada ejemplo secundario (por ejemplo, el diálogo de error como secundario de los diálogos Usar diálogos del sistema) debe transferirse a su elemento superior.

NOTA 1: Hay ejemplos que existen en electron-api-demos y en la documentación principal (por ejemplo, combinaciones de teclas, arrastrar y soltar). En este caso, el ejemplo de electron-api-demos debe tener prioridad y se debe ignorar el ejemplo de la documentación principal.

NOTA 2: Muchos ejemplos de la aplicación electron-api-demos tienen una vista previa de la demostración en vivo de la función o funcionalidad descrita. Esta funcionalidad se ignorará hasta la integración de Electron Fiddle en las semanas 9 y 10.

1. Actualiza la página con todas las funciones disponibles (que se crearon durante la 3a semana) respetando la nueva jerarquía de ejemplos.

Las semanas 6 y 7 se dedicarán a transferir ejemplos de electron-api-demos a la documentación principal según la plantilla que se describió anteriormente. Como paso final, el repositorio electron-api-demos debería eliminarse o dejarse de estar disponible.

SEMANAS 8 A 10

Dedicaremos la semana 8 a preparar una plantilla (una forma) de cómo se integrará Electron Fiddle en la documentación principal. Los chicos de Electron ya lanzaron esta iniciativa (consulta los detalles en el problema #20442) junto con voluntarios de la comunidad, pero requiere una finalización adecuada.

Para continuar con las muestras de Fiddle, la plantilla básica podría verse de la siguiente manera: 1. Elige un ejemplo de la documentación principal (por ejemplo, la guía de inicio rápido). En este punto, la documentación también debe contener ejemplos de electron-api-demos. 2. Recrea el ejemplo en Electron Fiddle (usa el código de ejemplo o el código fuente como punto de partida). 3. Guardar el Fiddle localmente en una carpeta. 4. Mueve el ejemplo a /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * La lista de ejemplos completos se describe en la sección “Lista de demostraciones” del problema. 5. Agrega el botón "Launch in Fiddle" como se describe en el comentario inicial en el número 2848.

Las semanas 9 y 10 se dedicarán a integrar ejemplos de electron-api-demos (que ya se convirtieron en Fiddles) a la documentación principal según la plantilla descrita anteriormente.

SEMANA 11

Esta semana se dedicará por completo a la finalización del proyecto de escritura después de la migración exitosa del repositorio electron-api-demos y los ejemplos de Electron Fiddle. Esto incluye lo siguiente: - Verificar que todos los ejemplos de código existentes tengan el botón “Launch in Fiddle” - Verificar que todos los ejemplos de código existentes funcionen correctamente como Fiddles - Verificar que la documentación principal ya no haga referencia al repositorio electron-api-demos

SEMANA 12

Finalización del trabajo completado. Verificaciones de aceptación