Un enfoque práctico de Cómo Documentar un Plugin de WordPress con recomendaciones que puedes adaptar a tu WordPress.
El lector más frecuente de tu código eres tú dentro de seis meses. Escribe para esa persona, que no recuerda nada.
Explica el Porqué, No Solo el Qué
El código ya dice lo que hace. Una buena documentación de plugins WordPress registra por qué lo hace así: la restricción, el compromiso, el error que moldeó una decisión. Esas notas son lo primero que se pierde cuando un proyecto cambia de manos.
Guarda una nota breve de arquitectura que liste puntos de entrada, hooks usados, opciones guardadas y tablas creadas.
Mantén la Documentación Junto al Código
La documentación que vive en el repositorio cambia en el mismo commit que el código que describe. Un readme, un changelog y los docblocks cubren casi todo sin otra herramienta.
La documentación pública, como las páginas de nuestro centro de documentación, se escribe para usuarios y se actualiza solo cuando cambia el comportamiento.
El Conjunto Mínimo Útil
Estos cuatro documentos cubren casi cualquier plugin.
- Readme: qué hace, requisitos e instalación.
- Changelog: cada versión, agrupada por tipo.
- Nota de arquitectura: estructura, hooks y datos.
- Referencia de hooks: filtros y acciones que expones.
Revisa la Documentación como Revisas el Código
Añade comprobaciones de documentación a tu rutina de lanzamiento. Un plugin sin notas exactas es un plugin esperando a ser reescrito.
Respuestas rápidas
¿Cuál es la documentación mínima de un plugin?
Un README con propósito, pasos de instalación y requisitos, una lista documentada de hooks y ajustes, y un changelog.
¿Debo comentar todas las funciones?
No. Comenta la intención y las decisiones poco obvias, no lo que el código ya dice. Mantén los comentarios breves y actualizados.
Parte del diario de WP StudioDDC. Sigue el trabajo de Didac Soria y del estudio de plugins a medida StudioDDC.
El Abandono del Carrito Empieza a Menudo con un Fragmento Lento
Deja una respuesta