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:
- Electron
- Escritor técnico:
- Señor Oro
- 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 crear aplicaciones multiplataforma de escritorio con JavaScript, HTML y CSS. Una colección de apps creadas con Electron tiene casi 900 entradas, y esta lista crece continuamente. Algunas de las herramientas para desarrolladores más populares, como Visual Studio Code, Atom, Postman, Slack y GitKraken, están integradas en Electron.
La popularidad de Electron radica en su simple curva de aprendizaje y su bajo umbral de entrada: todos los que conocen JavaScript, HTML y la pila de CSS pueden crear sus propias aplicaciones. Las enormes tasas de crecimiento generales dictan la necesidad de crear instructivos y guías de introducción que sean fáciles de comprender y usar.
El objetivo del proyecto es brindar confianza a los creadores de aplicaciones nuevos en el framework de Electron y brindarles una experiencia uniforme y optimizada para desarrollar sus propias aplicaciones de Electron desde cero.
Problemas del proyecto
La siguiente es 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 poco intuitiva sobre los pasos del desarrollo de aplicaciones 2. Información dispersa y redundante relacionada con el proceso de desarrollo de aplicaciones 3. Piezas desorganizadas de instrucciones de la guía de “introducción” sin una única fuente de verdad.
PROPUESTA DE PROYECTO
Según el objetivo del proyecto y los problemas descritos anteriormente, a continuación se presenta una lista de las mejoras propuestas: 1. Actualiza las guías existentes. Para que los primeros pasos sean fluidos y coherentes, debes actualizar los siguientes documentos con un cambio gradual de simple a más complejo: - Entorno del 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 desarrolladores nuevos lo que es esencial para comenzar y lo que puede considerarse más pasos, 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 pasos siguientes. 3. Organiza y unifica la documentación de desarrollo de aplicaciones. Todas las funciones deben tener un conjunto unificado de instrucciones para instalarla o habilitarla, cómo comenzar rápidamente, cómo trabajar con una app después del primer lanzamiento y cómo distribuirla. 4. Incluir 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 Cómo agregar funciones a tu app para mantener la coherencia con la estrategia de contenido de una única fuente fiable. 5. Integra ejemplos de Electron Fiddle en la documentación. Con este paso, los nuevos desarrolladores podrán ver con mayor facilidad cómo funciona un fragmento de código en particular sin tener que repetir los pasos manualmente. La integración incluye escribir muestras 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 solicitudes - Familiarízate con la comunidad y las personas con las que trabajarás. Consulta las guías de contribución de la comunidad y las prácticas recomendadas. 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: Alinéate con los mentores en cuanto a los hitos y entregables del proyecto. Semana 2: Revisa el entorno del desarrollador y escribe las páginas de tu primera app Electron. Semana 3: Revisa la arquitectura de aplicaciones, agrega funciones a tu aplicación, App Packaging y páginas de distribución. Crea una página de resumen con una lista de funciones que se puedan 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 a 7: Migra el repositorio 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 a 10: Integra el electron Fiddle en la documentación principal. Semana 11: Finalización de la estructura y las páginas de documentación principales después de migrar el repositorio electron-api-demos y las muestras de Electron Fiddle. Semana 12: evaluación de los resultados.
DESCRIPCIÓN DETALLADA DE LOS HITOS
PERÍODO DE REVISIÓN DE LA POSTULACIÓN 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 y a 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.
VÍNCULOS CON LA COMUNIDAD
Este tiempo se dedicará a un análisis más profundo de la carpeta de documentación junto con su hoja de ruta. A partir de esa información, será posible identificar los puntos débiles (por ejemplo, partes incompletas o faltantes) que se pueden mejorar. Crear solicitudes de extracción (cuando sea posible) para llenar los vacíos.
SEMANA 1 - SEMANA 2
La primera semana se dedicará a la comunicación con los mentores para acordar los hitos esperados y su entrega oportuna.
La segunda semana tratará sobre cómo revisar el entorno del desarrollador y escribir tu primera página de Electron. En la página Entorno para desarrolladores, se incluirá la reescritura de la descripción general y la revisión de texto. Para la página Escribir tu primera app Electron, se incluirá hacer de la página una guía paso a paso coherente con puntos de inicio y fin claros, eliminar la información redundante (como dos bloques de código similares bajo El Desarrollo Electrónico en Nutshell y cómo probar esta sección de ejemplo).
Ítems: Guías introductorias revisadas y fáciles de seguir sobre cómo iniciar un inicio rápido con aplicaciones de Electron.
SEMANA 3
Esta semana se dedicará a lo siguiente: 1. Mejoras en la página de la Arquitectura de aplicaciones Esto incluye lo siguiente: - la reescritura de la información existente en la sección Procesos principal y del procesador para que sea más intuitiva y sencilla para los lectores nuevos - agregar una representación visual de la arquitectura, cómo se conectan los procesos, cómo se comunican y su diferencia principal. Ejemplos de elementos visuales: Uno, dos, tres (baja calidad). 2. Unificación de la información sobre todas las funciones que puedes agregar a tu aplicación Electron. Esto incluye reescribir 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 (resumen) con todas las funciones disponibles para usar. Las instrucciones unificadas pueden tener el siguiente aspecto: - Descripción general - Ejemplo: - Muestra de código. - Ejemplo visual (cuando sea posible).
- simplificar la página Application Distribution. Esto incluye lo siguiente: a. fusionar el empaquetado de aplicaciones con la guía de Application Distribution b. dividir los métodos de distribución en automático y manual c. tomar electron-forge 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 de origen y crear archivos asar como ejemplos de distribución manual #### SEMANA 4 Esta semana se dedicará a reestructurar el directorio de documentación. En él se incluye lo siguiente:
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
Esta categoría contendrá instructivos básicos (instalación, configuración y distribución) para crear una serie coherente de guías que permitirán a los usuarios principiantes comenzar con una guía de inicio rápido desde cero. Cada guía debe contener enlaces a las guías anteriores o siguientes de la serie.
La estructura puede verse de la siguiente manera: 1. Requisitos previos 2. Instala Electron. 3. Crea una aplicación básica. 4. Empaquetar y distribuir la aplicación
Después de completar la sección de guías 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 en su totalidad.
La categoría Aprendizaje de los conceptos básicos contendrá las guías destinadas a fortalecer los conocimientos sobre Electron y a ampliar la aplicación creada en las secciones de la Guía de inicio rápido. Estas guías incluyen lo siguiente: - Arquitectura de aplicaciones - Cómo agregar funciones a tu app - Plantilla y CLI
La categoría Pasos avanzados contiene guías más avanzadas diseñadas para configurar y mejorar tu aplicación de Electron: - Pruebas y depuración - Accesibilidad - Seguridad - Actualizaciones
2) Reduce la cantidad de páginas de documentación. La versión actual de la documentación contiene un cierto grado de contenido superpuesto e instrucciones sin clasificar. Por ejemplo: - Instalación y instalación de Electron en la escritura de tu primera app. - Cómo empaquetar y empaquetar tu app en un archivo de la distribución de aplicaciones. - Instrucciones sin clasificar en las categorías Detalle y Avanzada: Sugerencia: Mueve los siguientes documentos a GitHub y exclúyelos de la documentación principal. Estos documentos son específicos para las pautas de desarrollo de Electron y el repositorio de código fuente es el primer lugar para buscarlos: - Developing Electron - Chromium Development - Desarrollo de V8 - Problemas en Electron - Parches en electron - Solicitudes de extracción - Estructura del directorio del código fuente - Prueba - Estilo de codificación
La idea principal de la reducción es deshacerse de una cantidad opresiva de guías disponibles, unir las dispersas piezas de información del rompecabezas y brindarles a los principiantes una versión más estructurada, fácil de navegar y fácil de usar de la documentación de Electron.
SEMANAS 5 A 7
La semana 5 se centrará en preparar una plantilla (una forma) de integrar electron-api-demos en la documentación principal. Esta plantilla puede tener el siguiente aspecto: 1. En la documentación principal, en "Cómo agregar funciones a tu app", crea las categorías representadas en electron-api-demos. A través de 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 elemento secundario de los diálogos de Uso del sistema) debe transferirse bajo su elemento superior.
NOTA 1: Hay ejemplos que existen tanto en electron-api-demos como en la documentación principal (por ejemplo, combinaciones de teclas y arrastrar y soltar). En este caso, el ejemplo de electron-api-demos debería tener la 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 característica o funcionalidad descrita. Esta funcionalidad se ignorará hasta la integración de Electron Fiddle en las semanas 9 a 10.
- Actualiza la página con una lista de todas las funciones disponibles para usar (que se crearon durante la Semana 3) 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 de acuerdo con la plantilla descrita anteriormente. Como paso final, el repositorio electron-api-demos debería borrarse o quedar obsoleto.
SEMANAS 8 A 10
La semana 8 se centrará en preparar una plantilla (una forma) de integrar Electron Fiddle en la documentación principal. Esta iniciativa ya la lanzaron miembros de Electron junto con voluntarios de la comunidad (consulte los detalles en el problema n.o 20442), pero se debe completar de manera adecuada.
Para continuar con las muestras de Fiddle, la plantilla básica puede tener el siguiente aspecto: 1. Elige un ejemplo de la documentación principal (como la guía de inicio rápido). En este punto, la documentación también debe contener ejemplos de electron-api-demos. 2. Vuelve a crear el ejemplo en Electron Fiddle (con el código de ejemplo o el código fuente como punto de partida). 3. Guarda 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 del problema n.o 2848.
Las semanas 9 y 10 se dedicarán a integrar ejemplos de electron-api-demos (que ya se han convertido en Fiddles) a la documentación principal de acuerdo con la plantilla descrita anteriormente.
SEMANA 11
Esta semana se dedicará por completo a finalizar el proyecto de escritura después de una migración exitosa del repositorio electron-api-demos y las muestras de Electron Fiddle. Esto incluye lo siguiente: - comprobar que todos los ejemplos de código existentes tengan el botón "Launch in Fiddle" - comprobar 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 terminado Verificaciones de aceptación