Redacción de documentación para el marco de su tema de WordPress

Por lo tanto, ahora tiene un marco de tema de WordPress. ¡Felicidades! El arduo trabajo que ha puesto en desarrollarlo se verá recompensado a largo plazo y hará que su proceso de desarrollo sea más sencillo, ágil y eficiente..

Pero necesita hacer una última cosa antes de que termine, y eso es documentar su marco. Como mínimo, deberá asegurarse de que se usen buenos comentarios en todo el código, pero también es útil escribir otra documentación para poder realizar un seguimiento de los archivos, funciones y filtros que conforman la API de su marco..

Las opciones que cubriré son:

  • Comentando
  • Creando un archivo readme
  • Uso de herramientas automatizadas de documentación.
  • Creando un wiki
  • Creando un sitio web
  • Creando tutoriales o grabando videos.

Tenga en cuenta que si bien mencionaré algunas herramientas de documentación, este tutorial no sirve como una recomendación, ya que no las he utilizado para mi propio marco, por lo que deberá hacer su propio juicio en cuanto a su idoneidad..

Escribir comentarios de calidad

Los comentarios son particularmente importantes cuando otros desarrolladores trabajarán con tu código (por ejemplo, si eres parte de un equipo o si vas a lanzar tu framework). Pero también son invaluables si está trabajando por su cuenta, ya que es muy fácil olvidar exactamente lo que hace una pieza de código cuando se edita un año o más más adelante..

Imagina que has usado tu marco para construir un sitio de cliente. Dos años a partir de ahora, el sitio desarrolla un problema a las 5:30 de la tarde de un viernes. Los buenos comentarios pueden hacer la diferencia entre solucionar los problemas rápidamente y estar en casa durante el fin de semana, en lugar de pasar por cientos de líneas de código y perder tu salida nocturna del viernes.

Aquí hay algunos consejos para buenos comentarios:

  • Use comentarios al principio de su archivo para explicar lo que hace el archivo. Por ejemplo, en los archivos de plantilla, incluya una nota sobre los datos que muestra y las personalizaciones que haya realizado en el bucle u otras partes del archivo; y en los archivos de complementos agregue una nota sobre su funcionalidad. Por ejemplo. el comentario a continuación les dice a los usuarios el nombre del archivo de plantilla, qué hace, el tema del que forma parte (@paquete), y qué versión del tema ha estado en su lugar desde (@ya que). Deberías usar un sistema similar para archivos de plugin..
/ ** * Nombre de la plantilla: sidebar-products.php * * El archivo de inclusión utilizado para la barra lateral en las páginas que utilizan la plantilla single-product.php. Muestra una galería de imágenes de productos (omitiendo la imagen mostrada que se muestra en el contenido). * * @package wpptl-theme-framework * @since version 1.0 * /
  • Use comentarios para delimitar las secciones de su código, no solo en las hojas de estilo sino también en los archivos de plantillas de temas y archivos de funciones..
  • Comenta cualquier cosa que no sea estándar.
  • Comente cualquier cosa que le haya llevado un rato hacer ejercicio: use comentarios detallados para que cuando vuelva a hacerlo no tenga que volver a pensarlo.
  • Comente cualquier cosa que sepa que otra persona estará trabajando, por ejemplo, si sus archivos de temas contienen secuencias de comandos que le pedirá a otro desarrollador que perfeccionen, agregue comentarios que expliquen dónde se aplican en el sitio..
  • Use la redacción en sus comentarios que puede encontrar usando una búsqueda más adelante, así que no abrevie, y use términos que otros puedan entender..
  • Siempre que comente algún código, agréguese un comentario que contenga la razón. De esa manera, si olvida eliminar el código después de haber terminado o si desea volver a agregarlo en el futuro, sabrá lo que está sucediendo..
  • En caso de duda, añadir un comentario.!

Creando un archivo readme

UNA readme.txt archivo es el siguiente nivel después de comentar. Es un archivo único que incluye en su tema, que contiene información sobre el tema..

El paquete de códigos que acompaña a esta serie incluye un sencillo readme.txt expediente:

Creación de su propio marco temático de WordPress Este tema es compatible con la sexta parte de esta serie para wptutsplus. El tema incluye los siguientes archivos de plantilla: archive.php index.php page.php - para páginas estáticas page-full-width.php archive.php - para páginas de archivos header.php sidebar.php footer.php loop.php loop-single .php loop-page.php functions.php El tema admite imágenes destacadas, menús y widgets, y los utiliza de la siguiente manera: Imágenes destacadas: se muestran en las plantillas de archivo e índice, si están presentes, utilizando el tamaño mediano. Menús: el menú predeterminado está en header.php, y usa el estilo de administración de menús. El tema usa CSS orientado a objetos (OOCSS). Las siguientes clases son para el diseño y puedes usarlas en tus páginas y publicaciones. Son receptivos, por lo que cambiarán de tamaño en pantallas más pequeñas (por ejemplo, la clase media es de ancho completo en los teléfonos). Ancho completo. Tres cuartos .tres tercios. Medio. Tercer tercio .quarter Hooks Hay 7 ganchos de acción: Arriba del encabezado Dentro del encabezado Antes del contenido Después del contenido En la barra lateral En el pie de página Después del pie de página Hay 3 enlaces de filtro: 1 en el encabezado 2 en el pie de página Áreas de widgets Hay seis áreas de widgets, todas agregadas a través del archivo widgets.php: - uno en el encabezado - uno en la barra lateral - cuatro en el pie de página

Si quieres hacer tu readme archivo más fácil de usar, es posible que desee considerar la creación de un readme.html archivo en su lugar que se abrirá en el navegador de un usuario. Puedes usar CSS para marcar tu readme archivar y facilitar la lectura.

Si desea lanzar su tema al público a través del repositorio de temas de WordPress, se espera que proporcione un readme.txt Archivo como forma mínima de documentación. Cubriré esto con más detalle en el tutorial final de esta serie, sobre la liberación de su marco temático..

Uso de herramientas de documentación automatizadas

Si planea continuar desarrollando su marco y no quiere perder mucho tiempo escribiendo manualmente la documentación de cada nueva característica, una herramienta de documentación automatizada puede ser la respuesta..

La mayoría de estos implican el uso de etiquetas o sintaxis específicas para permitir que el sistema identifique dónde generar la documentación. Ejemplos incluyen:

  • PHPDocumentor que es específico de PHP
  • APIgen también PHP específico
  • Doxygen
  • Groc

Si va a utilizar una de estas herramientas, vale la pena dedicar un tiempo a identificar la mejor para usted antes de comenzar, ya que no podrá transferir su documentación de una a otra.. 

Pero una vez que se haya familiarizado con el sistema y lo haya configurado, una herramienta automatizada como esta le puede ahorrar mucho tiempo y evitar brechas en su documentación en el futuro, ya que estará tan ocupado escribiendo el código. no tienes tiempo para actualizar tus documentos.

Creando un wiki o sitio web

Esta opción será más útil y solo vale la pena hacerlo si ve que su marco de trabajo crece con el tiempo y obtiene una base de usuarios importante. Todos los marcos temáticos principales tienen sus propios sitios web con documentación, que está disponible de forma gratuita o está disponible solo para los miembros..

El sitio web para respaldar su marco podría formar parte de su estrategia de monetización; el marco de tema híbrido, por ejemplo, es gratuito, pero la documentación y el soporte en el sitio web que lo acompaña solo están disponibles para los suscriptores de pago..

Alternativamente, si está lanzando su marco como un producto premium, puede requerir que los suscriptores inicien sesión en los documentos, o puede hacer pública su documentación con la esperanza de que aliente a más personas a comprar..

Si su marco es completamente gratuito, puede elegir crear un sitio web gratuito con documentación, como es el caso del marco Wonderflux:

Alternativamente, puede decidir crear un wiki, que tiene la ventaja de permitir que sus usuarios contribuyan a los documentos. Esto llevará más tiempo para configurar que un sitio web en la mayoría de los casos, pero podría ser una herramienta valiosa para la comunidad que usa su marco. Puede crear una wiki usando un complemento para el sitio de WordPress de su marco.

Creando tutoriales o grabando videos

Los tutoriales pueden ayudar a los nuevos usuarios, en particular a aquellos que no pueden escribir código, a familiarizarse con su marco más rápido que la documentación estándar. Los videos llevan esto un paso más allá, brindando una guía visual fácil de usar y una excelente herramienta de marketing.

El marco de Genesis tiene una gama de tutoriales para usuarios que solo están disponibles para suscriptores de pago:

Mi propio marco de Edupress tiene una serie de videos tutoriales que creé para ayudar a los usuarios con un grado variable de experiencia en computadoras y poca experiencia en el uso de WordPress:

Estos se muestran en el sitio web público y también en los paneles de control de los usuarios para que puedan acceder fácilmente a ellos mientras trabajan con el marco. Si crea documentación, tutoriales o videos para su marco, puede incluir una pantalla en el panel con detalles de sus documentos..

Sin embargo, crear tutoriales o videos requiere mucho tiempo y requiere mucho trabajo para hacerlo bien: los tutoriales mal escritos o los videos mal producidos se reflejarán mal en su marco y pueden hacerle más daño que una forma más simple de documentación.. 

Resumen

Quienquiera que vaya a usar el marco de su tema, algún tipo de documentación es esencial. Ya sea que esté desarrollando el marco para usted y su equipo, o liberándolo para un uso más amplio, necesitará registrar información sobre la estructura de archivos y la API.

Las opciones que he discutido anteriormente van desde los comentarios simples hasta los videos más complejos, con todo lo que hay en el medio. Lo que decida hacer dependerá de las necesidades de sus usuarios y puede cambiar con el tiempo a medida que obtiene una base de usuarios más amplia..