Documentación del producto para profesionales de WordPress

Publicado: 2017-07-28

La documentación del producto generalmente se considera intrascendente, que puede reducir las esquinas. No se ve como algo que pueda ofrecer valor al cliente, o como algo que posiblemente podría afectar áreas comerciales clave como ingresos y marketing. Por supuesto, como profesional de WordPress, no necesitará escribir documentación de la misma manera que Atlassian o Cisco. Por lo general, cuando las personas piensan en "documentación", evocan imágenes de guías de usuario impresas y gruesas, indexadas alfabéticamente en un estante muy grande que nadie lee nunca.

Pero esto ha cambiado:

Con la llegada de Agile y DevOps, el envío de software se ha vuelto más rápido y el ciclo de desarrollo también se ha vuelto más dinámico. Y como resultado, la documentación ahora refleja el estado actual en la versión más reciente, en lugar de ser algo estático escrito en papel para siempre. La documentación está integrada en el ciclo de desarrollo y se actualiza con la misma frecuencia que el software.

¿Por qué los profesionales de WordPress deberían preocuparse por la documentación del producto?

La documentación útil y actualizada no solo facilita la vida de sus usuarios, sino que también agrega un nivel de pulido que se convierte en un activo de marketing como ningún otro. Por el contrario, la mala documentación tiene un impacto negativo. Probablemente haya experimentado esto usted mismo: tenía un problema para el que estaba tratando de encontrar una solución en la documentación y cuando no lo hizo, terminó frustrado (y probablemente enojado). Solo empeora si está pagando por el producto.

Si está trabajando en una agencia de WordPress, entregar documentación en todas las áreas de un proyecto, desde el diseño inicial hasta los activos, agregará un nivel de profesionalismo que muestra que:

Prestas atención a los detalles.
Te preocupas por tu cliente lo suficiente como para hacer un esfuerzo adicional.
Eres transparente y confiado en tus decisiones de diseño y proyectos técnicos.

Mike Puterbaugh, vicepresidente de marketing de MindTouch, escribió un artículo de Mashable que describe las 5 razones por las que la documentación de su producto es un activo de marketing. Concluyó con lo siguiente:

No es una empresa sexy, pero le hará ganar el respeto de sus compañeros, una gestión empresarial más eficaz y un equipo más colaborativo. Porque no se trata de este trimestre o de este año, sino de afectar la ventaja competitiva y el crecimiento a largo plazo.

Ahora que hemos establecido suficiente motivación, haremos lo siguiente:

Explore los diferentes tipos de documentación de productos que son relevantes para WordPress.
Discuta las necesidades de cada tipo de documentación y ofrezca consejos prácticos.
Ofrezca una guía inicial sobre cómo puede planificar y colaborar en la documentación del producto. Particularmente si está trabajando en una agencia de WordPress.

Tipos de documentación de productos de WordPress

Un producto de WordPress no se trata solo de complementos y temas. En esta sección, también discutiremos la ayuda en línea, las API REST y algo curioso llamado microcontenido.

Complementos de WordPress

La documentación del complemento de WordPress debe atender a dos multitudes: usuarios y desarrolladores. Las necesidades de documentación de cada uno son diferentes, al igual que el estilo de escritura utilizado.

Usuarios

Las necesidades de documentación de los usuarios giran principalmente en torno a la resolución de problemas y la configuración. Agregue a esto que necesita presentar su complemento de una manera atractiva para que los usuarios lo prueben. Cada complemento tiene su propia página en el mercado de complementos de WordPress. Tenga en cuenta los siguientes puntos:

Escriba una descripción convincente y útil que fomente la descarga y el uso.
Agregue capturas de pantalla anotadas desde la página de configuración del complemento Dashboard con descripciones.
Ponga preguntas en las preguntas frecuentes que sean útiles y no trilladas.
Tenga un registro de cambios actualizado y bien escrito. No agregue notas crípticas o concisas allí.

Debe recordar que cuando los usuarios utilizan la documentación, probablemente tengan prisa y estén ansiosos por encontrar una solución. Escribe de forma clara, sencilla y concisa. No se lo pongas más difícil de lo que ya es.

Desarrolladores

Además de seguir las mejores prácticas de software y los estándares oficiales de codificación de PHP, debe centrar su atención en las siguientes áreas:

ganchos de complemento

Estos hacen el trabajo de modificar el comportamiento de WordPress. Es muy probable que su complemento de WordPress los use. Dado que los complementos son una parte importante del código, debe documentar cómo los usa y en qué funciones de WordPress están involucrados.

etiquetas de plantilla

Las etiquetas de plantilla son otra forma en que un complemento de WordPress mejora la funcionalidad. Documente las funciones de etiqueta de plantilla que ha escrito. Incluya ejemplos de cómo otros usuarios o desarrolladores pueden usar las etiquetas en su sitio de WordPress.

opciones

Las opciones son una forma de almacenar información particular en una base de datos de WordPress. Esto se hace a través de las funciones add_option y get_options. En este caso, documente los parámetros que pasa a estas funciones.

base de datos

Los complementos frecuentemente leen y escriben muchas cosas diferentes de una base de datos. Dado que estas son operaciones fundamentales, documentarlas ayudará en gran medida a otros desarrolladores a comprender cómo funciona su complemento.

Temas de WordPress

Hay dos áreas diferentes en las que puede crear documentación para temas. El primero son los archivos fuente. Los archivos CSS comentados son más fáciles de entender y leer que los que no los tienen. Usa una herramienta como css_doc para ayudarte. Esto genera un estilo de documentación JavaDoc y se puede publicar:

La otra área son las guías de estilo. Estos documentos describen cómo deben verse los elementos y en qué casos deben usarse. Refuerzan la coherencia y también facilitan la colaboración. Puede leer el artículo 20 impresionantes ejemplos de guías de estilo de marca de Hubspot, ya que contiene muchos ejemplos excelentes.

Nuevamente, no olvide consultar los estándares oficiales de codificación CSS de WordPress.

Documentar los elementos de diseño con tanto detalle también ayuda a la incorporación de nuevos empleados si es una agencia de WordPress. Las guías de estilo se pueden utilizar como tutoriales o material de referencia para trabajos de clientes nuevos y anteriores.

Ayuda en linea

Dado que la ayuda en línea tiene como objetivo resolver un problema de usuario en particular, el camino a seguir es comenzar con una lista de tareas y problemas comunes. Aunque la lista al principio no será exhaustiva, tómese el tiempo para producir tantos elementos concretos como pueda. La idea es escribir un archivo de ayuda en línea para cada una de estas tareas y problemas, y vincularlos a información relacionada. Puede crear viajes de usuario para mapear las diferentes rutas que un usuario puede tomar y hacer dentro de su aplicación. Sumergirte en los correos electrónicos de soporte para detectar preguntas comunes y áreas problemáticas es una buena manera de mantener tu base de conocimientos actualizada y útil.

Barry J. Rosenberg, autor de Spring into Technical Writing ofrece los siguientes consejos para escribir buenos archivos de ayuda:

Mantenga cada archivo de ayuda lo más breve posible. Prefiere las listas numeradas a las listas con viñetas. No se desvíe, no haga notas al pie y no quiera. Mantenga cada archivo de ayuda enfocado en una sola tarea discreta.

microcontenido

El microcontenido tiene dos definiciones: la primera es contenido como titulares y secciones que los usuarios hojean para obtener la esencia de un artículo en particular. El segundo son pequeños fragmentos de contenido que pueden valerse por sí mismos y se utilizan para mejorar la experiencia del usuario. Un excelente ejemplo en particular que tenemos en mente es el bit "varias personas están escribiendo..." de Slack. (aunque Slack está lleno de microcontenido excelentemente escrito).

Ese bit se activa cuando más de 3 personas escriben simultáneamente en el mismo canal. En lugar de simplemente imprimir una lista de personas que actualmente escriben, Slack toma esta información aburrida y le agrega algo de diversión. La discusión está empezando a ponerse muy caliente, y se nota. Es un excelente ejemplo de cómo la documentación del producto (los mensajes de la aplicación son parte de eso, ¿no?) hace que la gente hable de ti (y cree divertidos memes como el anterior).

API REST

La documentación de las API REST es un arte aparte en sí mismo. Al igual que con todos los escritos técnicos, debe buscar la concisión, la claridad y la simplicidad en las definiciones. Dado que las API REST tienen su propio formato y complejidades, no podría hacer nada peor que estudiar la excelente guía para documentar las API de Tom Johnson en su blog Preferiría estar escribiendo.

Colaboración y planificación de la documentación.

En última instancia, la documentación debe ser parte del diseño del producto. Como tal, debe abordarlo como si tuviera una canalización adicional en su ciclo de software. Esto significa usar repositorios de software para almacenar la versión de documentación más reciente, usar rastreadores de errores/problemas para monitorear tareas y problemas, incluir la planificación de proyectos de documentación en su hoja de ruta y, por último, pero no menos importante, colaborar con otras personas. Un esquema aproximado de cómo empezar podría ser el siguiente:

Registre todo lo que el usuario querría saber, así como las áreas para las que necesitará escribir texto.
Una vez que tenga todo, agrúpelos en categorías y forme títulos de documentos.
Escriba una especificación para cada documento que detalle cosas como el título, la descripción, el público objetivo, los medios (qué forma tendrá el documento), la extensión, cuánto tiempo llevará, etc.
Agregue las estimaciones de las especificaciones de la documentación a la planificación de su proyecto.

Dado que la documentación del producto abarca todas las áreas, es casi seguro que necesitará trabajar con diferentes personas dentro de la organización. Es una buena idea sentarse y ponerse de acuerdo sobre algún tipo de proceso de cómo irá todo esto. Como en todo proyecto, debe identificar a las partes interesadas que brindarán asistencia técnica, así como a quienes revisarán y editarán los cambios.

Debe haber diferentes etapas del proceso. Estos deben indicar dónde se recopila la información, cuándo se escribe el documento, cuándo está listo para la revisión literaria, los comentarios técnicos, la publicación, etc. Enfatice la diferencia entre comentarios literarios, técnicos y relacionados con el contenido. Por ejemplo, no es realmente útil cuando le pide a un líder de equipo que comente su documento y, en lugar de información técnicamente relacionada, recibe quejas por la gramática y la puntuación.

Clausura

La documentación del producto es un activo que vale la pena a largo plazo. Da valor a tu cliente. Incluso podría ser tan bueno, como la documentación de la API de Stripe, por ejemplo, que la gente delira en los foros. Esto genera compromiso y anuncia su marca y su producto de una manera natural y poderosa. Cuando se combina con microcontenido creativo, logra lo que Mike Puterbaugh quiere decir cuando dice que la documentación del producto es el “arma secreta del marketing”.