Escritura de páginas de paquetes

Las pautas en esta página pueden ayudarte a crear buenas páginas de paquetes en pub.dev. Específicamente, esta página tiene consejos para escribir un mejor archivo README de paquete, que proporciona el contenido marcado como README (este documento) en la siguiente captura de pantalla:

Para obtener detalles sobre otras partes de la página del paquete, sigue estos enlaces:

1. Estructura del paquete
2. Favorito de Flutter (Flutter Favorite)
3. Puntuación del paquete
4. Editores verificados
5. Archivo pubspec

Es probable que las personas que encuentren tu paquete en pub.dev escaneen rápidamente el README al decidir si probar tu paquete. Un buen README capta la atención del lector y muestra que vale la pena probar tu paquete.

Aunque esta página presenta el README del paquete in_app_purchase, es posible que el tuyo no necesite ser tan grande o detallado. Si tu paquete es simple y no tiene una interfaz de usuario asociada, su README podría parecerse más al del paquete yaml.

Aquí tienes algunas sugerencias para crear un README que funcione bien en pub.dev:

1. Coloca una descripción corta al principio
2. Incluye contenido visual
3. Usa listas para presentar información importante
4. Incluye ejemplos de uso
5. Usa el formato de código de Dart
6. Menciona términos relacionados
7. Dile a los usuarios qué hacer a continuación

Según nuestra investigación de usuarios, los usuarios de paquetes solo dedican unos segundos a leer la descripción del paquete y decidir si leer el resto del README. Por lo tanto, debes describir de forma concisa lo que hace o logra el paquete, de un vistazo. Dedica algo de tiempo a elaborar una descripción corta y atractiva para ayudar al usuario a tomar decisiones.

Aquí hay algunos ejemplos de buenas descripciones:

• Un complemento (plugin) de Flutter para mostrar arcoíris.
• Utiliza el aprendizaje automático para categorizar los sonidos de las aves.

La información importante, como el estado del proyecto o las restricciones, también debe estar cerca de la parte superior. Por ejemplo:

• No funciona en versiones de iOS inferiores a la 10.3.

Aquí tienes una captura de pantalla de la página del paquete in_app_purchase, la cual comienza con una breve explicación del paquete y una advertencia:

Las insignias (badges) a menudo están cerca de la parte superior del README, ya sea arriba o abajo de la descripción corta.

Si la página de tu paquete es una pared de texto sin contenido visual, los usuarios pueden encontrarla intimidante y dejar de leer. Las imágenes son especialmente importantes si tu paquete admite interfaz de usuario, pero también son útiles para explicar conceptos importantes. En cualquier caso, el contenido visual puede ayudar a los usuarios a sentirse seguros a la hora de utilizar el paquete.

Coloca el contenido visual, como imágenes estáticas, GIFs animados y videos (como archivos MOV o MP4), cerca del principio del README, donde es probable que los usuarios los vean.

Las capturas de pantalla a continuación muestran cómo la adición de contenido visual hizo que la página del paquete in_app_purchase se viera informativa a primera vista. (La imagen de antes está a la izquierda; la de después está a la derecha).

Las listas pueden llamar la atención sobre información importante en tu README. Puedes utilizar listas para lo siguiente:

• Características clave del paquete
• Parámetros, atributos o propiedades
• Requisitos inusuales
• Funcionalidad que está fuera del alcance de tu paquete
• Un resumen del contenido de una página o de una sección dentro de una página (como esta lista)

Normalmente, las listas tienen viñetas, como la lista de arriba. Otra opción es utilizar una tabla, como la tabla de soporte de plataformas en la siguiente sección.

Primero, enumera claramente lo que puede hacer tu paquete. Algunos usuarios pueden estar buscando una característica muy específica. Ayuda a esos usuarios a descubrir si tu paquete cubre sus necesidades.

La siguiente captura de pantalla muestra cómo el README de in_app_purchase presenta las características del paquete:

La siguiente captura de pantalla muestra una tabla del README de just_audio que enumera las características del paquete y el soporte de plataformas:

Considera listar parámetros, atributos o propiedades para una referencia rápida. (Recuerda que el contenido del README del paquete aparece en la documentación de referencia de la API, así como en la página del paquete).

Por ejemplo, el paquete url_launcher tiene una tabla de esquemas de URL admitidos:

Enlazar a funciones o clases específicas en la documentación de referencia de la API también puede ser útil. Consulta el paquete async para ver un ejemplo.

Si tu paquete necesita una configuración específica, más allá de lo que requieren todos los paquetes, incluye las instrucciones de configuración en el README.

Por ejemplo, la siguiente captura de pantalla para el paquete google_maps_flutter muestra las instrucciones para comenzar con Google Maps Platform:

Para ayudar a los usuarios a saber si tu paquete puede serles de utilidad, enumera las características que los usuarios podrían esperar, pero que tu paquete no admite.

Aquí tienes algunos ejemplos de cuándo podrías querer enumerar la funcionalidad fuera de alcance:

• Si tu paquete de botones se enfoca solo en botones de texto y no en botones de iconos, déjalo claro en el README.
• Si tu paquete admite solo ciertas versiones de Android, dilo en el README.

A los usuarios les resulta más fácil navegar por una página o sección cuando tiene una tabla de contenidos. Si una sección de tu README es muy larga, considera la posibilidad de enumerar las subsecciones de forma clara al comienzo de la sección.

Por ejemplo, la sección "Uso" del README de in_app_purchase tiene muchos ejemplos. La siguiente tabla de contenidos ayuda a los usuarios a comprender qué ejemplos existen y a dirigirse al código que les interesa:

Si tu paquete parece prometedor, es posible que los usuarios deseen probarlo. Incluye una sección "Comenzar" o "Uso" que tenga al menos una muestra de código que los usuarios puedan entender fácilmente y, de manera ideal, que puedan copiar y pegar en su proyecto. Es aún mejor si puedes proporcionar más ejemplos con más detalles para ayudar a los usuarios a comprender tu paquete.

¡Recuerda que no todos los usuarios hablan inglés, pero todos hablan Dart! Los buenos ejemplos de código pueden ser de gran ayuda. Considera agregar ejemplos más completos bajo el directorio example de tu paquete, el cual pub.dev puede usar para rellenar una pestaña Examples (Ejemplos). Para más detalles, consulta Examples (Ejemplos) en las convenciones de diseño de paquetes.

La siguiente captura de pantalla muestra uno de varios ejemplos en el README para el paquete in_app_purchase:

Al agregar ejemplos de código, utiliza tres comillas invertidas más dart (```dart) en lugar de tres comillas invertidas (```). Como muestran los siguientes ejemplos, agregar dart le indica a pub.dev que use el resaltado de sintaxis de Dart:

final like = 'this';

final like = 'this';

A recent UX study found that many users use the within-page search feature (Command+F) to search for the feature they are looking for. Thus, be sure to mention important terms in the README, so that users can find them.

Por ejemplo, es posible que los usuarios quieran saber si el paquete in_app_purchase admite suscripciones integradas en la aplicación (in-app subscription). Un usuario que busque la palabra clave subscription podría abandonar la página si esta no utiliza ese término.

Después de mencionar todos los términos que la gente podría buscar, sé coherente con los términos que utilizas. Si es necesario, define claramente los términos.

Por ejemplo, el paquete in_app_purchase define underlying store (tienda subyacente) al principio:

El resto de la página utiliza consistentemente ese término:

Ayuda a tus usuarios a obtener más información sobre el paquete. Aquí tienes algunas sugerencias de qué decir a los usuarios potenciales:

• Dónde obtener más información sobre el paquete. Podrías enlazar a un artículo en Medium o a un video en YouTube.
• Dónde obtener ayuda para usar el paquete. Las posibilidades incluyen un rastreador de problemas (issue tracker), una sala de chat o una dirección de correo electrónico.
• Qué planeas hacer con el paquete. Una hoja de ruta (roadmap), ya sea en el README o en una página externa, puede ayudar a los usuarios a saber si la característica que necesitan llegará pronto.
• Cómo contribuir código al paquete.

La siguiente captura de pantalla muestra la parte del README de in_app_purchase que contiene información para posibles colaboradores:

Hemos sugerido siete consejos para un buen README en esta documentación. Puedes aprender más sobre las recomendaciones comunes para la documentación de desarrolladores en la Guía de estilo de documentación para desarrolladores de Google. Algunos consejos adicionales incluyen:

• Suministra texto alternativo para las imágenes.
• Sé sucinto. No digas por favor.
• Mantén la longitud de línea <= 80 caracteres.
• Formatea el código correctamente (como lo haría dart format).

Para obtener más información sobre las buenas prácticas de README, consulta estos recursos:

Lista de verificación de README (README Checklist)

Una lista de verificación para escribir un README que ayuda a los lectores a sentirse seguros sobre tu proyecto.

Excelente README (Awesome README)

Una lista seleccionada y comentada de excelentes archivos README.

Crear un README (Make a README)

Una introducción a los archivos README, con una plantilla y sugerencias para un buen README.

Cómo escribir un gran README para tu proyecto de GitHub

Elementos clave de un buen README y una plantilla.

Es posible que las sugerencias de esta página y de otras no funcionen para todos los paquetes. ¡Sé creativo! Ponte en el lugar de los usuarios e imagina lo que el lector podría querer leer y saber. Tú eres la única persona que puede proporcionar la información que el lector necesita.