Documentación de plugins y temas de WordPress

La documentación es algo que normalmente solo se agradece cuando hay un problema y necesitas respuestas rápidamente. En este artículo, analizaremos las razones por las que escribir documentación para sus activos de WordPress es importante para su práctica como desarrollador de WordPress y la calidad de los temas y complementos que envía.

¿Por qué es importante la documentación?

Mantener un conjunto actualizado de documentación sobre sus proyectos, activos o productos es importante por muchas razones.

Primero, es una experiencia común mirar algo que hiciste hace 2 meses y no has tocado desde entonces, y no tener idea de lo que significa. Cuando lo desarrollas, lo tienes todo dentro de tu cabeza, pero esa comprensión no estará allí en el futuro. Entonces, ya sea usando comentarios de código en línea o escribiendo notas de texto sin formato en Markdown, ayuda mucho a salvar su yo futuro de la confusión.

En segundo lugar, mantener sus activos documentados es útil para otros desarrolladores de WordPress. Y esto tiene sentido incluso si eres un freelancer solitario (estás obligado a colaborar con otras personas en algún momento). Tendrán que usar esos activos o se les pedirá que los mantengan y/o actualicen. Es muy frustrante tener que usar código no documentado que está escrito por otra persona, que no está disponible para brindar soporte o explicar algunas partes difíciles.

Finalmente, la documentación agrega ese aspecto "pulido" a sus productos y sus clientes lo amarán más.

5 principios para una documentación eficaz

La redacción técnica es una disciplina en sí misma y se utiliza para comunicar información técnica de manera clara e inequívoca. (No se limita solo a las computadoras, los abogados y los médicos, por ejemplo, también usan su propio lenguaje técnico). Por eso, un documento que se considera redacción técnica suele seguir un estilo determinado y obedece a una serie de reglas.

¡Repasemos los 5 más importantes para que pueda escribir documentación efectiva para sus productos!

• Prefiere usar menos palabras de las que usaría normalmente en su escritura: cada palabra debe tener un propósito. Sea directo y simple. La documentación suele buscarse cuando una persona tiene problemas y quiere encontrar una solución rápidamente. Por ejemplo, una oración como "Si no se destruye el Objeto Q se producirán fugas de memoria" es preferible a "Si no se destruye el Objeto Q se producirán fugas de memoria".
• Prefiere usar la voz activa en lugar de la pasiva: " Haga clic en el botón en la parte superior derecha" en lugar de "Se debe hacer clic en el botón en la parte superior derecha". El uso de una voz activa aclara cualquier ambigüedad sobre quién hace qué. La voz pasiva solo se usa cuando necesita enfocarse en el objeto, en lugar de en el sujeto (por ejemplo, la plataforma de Pressidium está diseñada pensando en la seguridad ) .
• Utilice un lenguaje descriptivo cuando necesite describir conceptos e imperativo cuando necesite describir un procedimiento paso a paso (como tutoriales).
• Utilice listas de viñetas cuando necesite enumerar cosas que no tienen ningún orden y listas numeradas cuando el orden de los puntos sea importante.
• ¡Asegúrese de haber probado las instrucciones usted mismo, antes de presentarlas!

Documentación de complementos de WordPress

Los complementos de WordPress son como cualquier otra pieza de software. Proporcionan una cierta funcionalidad, requieren instalación y, a veces, también solución de problemas. No importa cuán simples sean, siempre es una buena idea proporcionar una cantidad adecuada de documentación, porque no todos los usuarios comparten la misma experiencia técnica.

Aloje su sitio web con Pressidium

GARANTÍA DE DEVOLUCIÓN DE DINERO DE 60 DÍAS

VER NUESTROS PLANES

¡Publicar su complemento de WordPress en wordpress.org le proporcionará un lugar para colocar instrucciones de instalación, capturas de pantalla, preguntas frecuentes e incluso un registro de cambios! Rellenarlos con información útil y de calidad es clave para que tu plugin sea más popular:

• Escriba una descripción convincente y útil que finalmente haga que el usuario descargue su complemento y visite su sitio web.
• Agregue capturas de pantalla anotadas que expliquen cada elemento de configuración de su complemento además de las que muestran cómo se ve su complemento en el navegador.
• Ponga preguntas en las preguntas frecuentes que no sean trilladas. Una buena manera de descubrir casos extremos extraños es pedirle a un amigo que no tenga conocimientos de informática que use su complemento.
• Tenga un registro de cambios actualizado y bien escrito. Las frases breves y crípticas son un gran no-no y muestran que realmente no te preocupas por tus usuarios.
• Asegúrese de que el código de su complemento esté bien comentado y siga las mejores prácticas de software y los estándares de codificación oficiales.

Si está atascado y necesita algo de inspiración, realice una pequeña investigación y vea cómo está escrito el texto en complementos populares que tienen cientos de miles de instalaciones, en comparación con los menos utilizados.

Documentar temas de WordPress

Documentar temas de WordPress es un asunto completamente diferente. El problema más común con los temas de WordPress es no saber qué sección corresponde a qué elemento visual. No todos dominan CSS:

• Crea una jerarquía de todas las secciones de tu CSS, con las descripciones correspondientes.
• Para cada sección, agregue una captura de pantalla anotada que detalle cada funcionalidad, junto con un pequeño ejemplo. No olvides usar la voz activa y el lenguaje imperativo, cuando muestres cómo hacer algo que requiera que el usuario siga instrucciones.
• Usa una herramienta como css_doc para ayudarte. Esto genera un estilo de documentación JavaDoc y se puede publicar.
• A veces, los comentarios del código no son suficientes y necesita crear un documento de guía de estilo para su tema CSS. Los documentos de la guía de estilo describen cómo deben verse los elementos y en qué casos deben usarse. Refuerzan la coherencia y también facilitan la colaboración. Vea este ejemplo de Google.
• Utilice un marco CSS como Blueprint CSS. Esto lo ayudará en el desarrollo al proporcionarle un conjunto de herramientas, como una cuadrícula personalizable, tipografía predeterminada que funciona, restablecimiento de CSS del navegador y mucho más.
• Nuevamente, no olvide consultar los estándares oficiales de codificación CSS de WordPress.