A continuación, se describen los pasos a seguir para crear artículos de documentación de producto de Athento:
1. Adapta el contenido al destinatario.
¿Para quién es el artículo que estás escribiendo?
- Si es un tema general enfocado a usuarios no técnicos, tenlo en cuenta para que el texto sea comprensible y cumpla su función de resolver un problema.
- Si es un tema concreto enfocado a usuarios técnicos, tenlo en cuenta y usa la jerga técnica y detalles necesarios para que ese tipo de usuario pueda configurar o resolver la incidencia para la que busca ayuda.
2. Sobre qué tienes que escribir.
Si existen unas instrucciones, consulta de cliente o petición de compañero/a del equipo, lee atentamente las directrices para comprender a qué necesita dar respuesta el artículo de documentación de producto que vas a escribir.
3. Plantea 2-3 encabezados que resuman las ideas que quieres transmitir en el artículo.
Sintetiza las ideas sobre las que quieres escribir.
Los encabezados que separan diferentes apartados del texto no sólo facilitan la escritura, también la legibilidad del artículo.
4. Distribución del artículo:
- Introducción: se introduce la idea principal, funcionalidad, concepto o pregunta frecuente que se va a explicar. 1 párrafo
- Encabezados: explica o describe las ideas principales. 2 a 3 párrafos debajo de cada encabezado.
- Cierre del artículo: si corresponde, se puede incluir un resumen, conclusión o links a información adicional.
5. Cómo redactar en la práctica:
-
Desarrolla la introducción y los encabezados.
- Explica o describe las ideas que has planteado en los encabezados. Utiliza ejemplos para ilustrar lo que quieres decir siempre que sea posible.
- Trata siempre de empezar por la mínima versión de la idea y después extiéndete.
- Separa siempre el texto en párrafos para facilitar su lectura.
- La clave de un buen texto está en oraciones cortas y fáciles de entender.
-
Editar también es escribir.
- Antes de dar por finalizado el artículo, vuelve sobre tus palabras y fíjate en los errores que se te pueden haber pasado (errores de digitación, palabras de más, ortografía, etc.).
- Comprueba también que el texto responde a la pregunta que se plantea en el artículo. Si no queda claro, haz cambios. Si te has extendido demasiado, valora dividir el texto en varias entradas al centro de documentación.
-
Pon bonito el texto.
- Utiliza negritas para destacar palabras clave o ideas clave. ¡No abuses de ellas!
- Utiliza las negritas de forma que los lectores puedan leer y entender la idea general del artículo leyendo sólo el texto destacado.
- Las cursivas también son un elemento auxiliar para destacar que puedes usar.
- Incluye los enlaces que consideres que facilitan consultar información relacionada con la pregunta frecuente o funcionalidad que se está resolviendo.
- Incluye imágenes o videos siempre que sea posible para explicar de forma gráfica cómo realizar una acción o configuración.
Es importante que recuerdes:
- A partir de 2024, hacer públicos e indexables por Google los artículos de documentación de producto.
-
Anonimizar los artículos: recuerda no incluir en artículos públicos datos de clientes o casos con datos de clientes. En los casos en los que la información quede incompleta sin incluir datos sensibles o confidenciales, hay dos alternativas:
- Crear el artículo con los datos esenciales y genéricos e incluir al final un texto sobre: "Para más detalle, entra en el siguiente enlace: XXX (enlace a un documento de acceso restringido interno). De esta forma, tenemos al menos lo básico publicado para que pueda ser indexado por buscadores y los datos de clientes solo los pueden ver usuarios registrados.
- Crear dos versiones de un mismo artículo: uno con información genérica y el otro con los detalles del caso de uso del cliente. Este último, con acceso restringido solo a usuarios registrados.
- *Antes de anonimizar un artículo ya existente o de hacer público un artículo existente a nivel interno que contiene daos sensibles, consulta si es adecuado hacerlo.
- Incluye etiquetas relacionadas con el tema del artículo para facilitar que se pueda encontrar el artículo en buscadores.
- Para publicar el nuevo contenido: asígnalo a la categoría "Novedades en la documentación" que queda pendiente de revisión.
Buenas prácticas y recomendaciones
- Faltas de ortografía: recomendamos que uses navegadores como Chrome que te permiten hacer revisión de la ortografía del artículo en tiempo real subrayando en rojo las palabras con errores ortográficos. También puedes pegar el texto en Word o Google Docs para que detecte las faltas ortográficas, corregirlas y pegar el texto correcto en Zendesk. En cualquier caso, asegúrate de no publicar el artículo con faltas de ortografía evidentes.
- Traducciones: una vez que termines de redactar el artículo, tradúcelo usando DeepL, Translate o ChatGPT e inclúyelo en la correspondiente pestaña en Zendesk. Consulta el tutorial sobre cómo crear artículos en Zendesk.
- Usa un tono neutro y en tercera persona.
- Usa los verbos en tiempos presentes. Son descriptivos y positivos. Evita los condicionales y futuros compuestos que añaden complejidad a la comprensión del texto.
- Nombra las imágenes: edita el nombre de las imágenes incluyendo un nombre breve relacionado con el contenido del artículo seguido de ‘_Athento’. Por ejemplo: integraciónSAP_Athento. Si hay varias imágenes similares o que explican los pasos de un mismo procedimiento, usa el mismo nombre numerando cada imagen. Por ejemplo: integraciónSAP_Athento, integraciónSAP2_Athento, integraciónSAP3_Athento. Editar el nombre de las imágenes es básico para el posicionamiento SEO, ya que permite posicionar nuestro contenido en el buscador de imágenes de Google o aparecer como resultado de búsqueda si no hay contenido en texto que resuelva la consulta del usuario.
- Incluye recuadros, flechas o marcas en las imágenes para guiar al usuario a comprender los comandos que tiene que seguir o dónde están los botones o información a consultar.
- Trata de hacerlo fácil, empieza por la mínima versión de contenido que puedas preparar para romper la barrera de la hoja en blanco y completa el artículo poco a poco.
- Hazlo hoy y no lo dejes para mañana.
Recomendaciones de seguridad
-
- En las capturas de pantalla o vídeos, oculta los marcadores del navegador u otras pestañas, o edita la captura/vídeo para eliminar esa información de marcadores y pestañas que puedan ser un indicio para ataques de seguridad.
- En las capturas de pantalla o vídeos, oculta las URLs en la medida de lo posible para evitar mostrar con qué herramientas internas trabajamos (que igualmente, puede ser un indicio para ataques de seguridad de la información).
- Para ocultar fácilmente la barra de marcadores de Chrome: Ctrl+Shift+B (en Windows).
Recomendaciones de posicionamiento SEO
Para optimizar para SEO los artículos del centro de documentación contamos con 2 herramientas fundamentales:
-
Utilizar la misma palabra clave en el título y primera línea del texto.
Para ayudar a los bots de los buscadores a saber sobre qué tratan los artículos y que puedan mostrarlos a los usuarios cuando hacen búsquedas es imprescindible identificar el tema sobre el que trata el artículo y dejarlo claro en el título y en la primera línea del artículo. Para ello, se utiliza lo que se denomina “palabra clave” sobre la que trata el contenido. Esa palabra clave puede ser solo una palabra o una frase de varias palabras. Así, cuando redactamos un artículo de documentación de producto hay que tratar de ser lo más específico posible acerca de qué trata el artículo y repetirlo en la primera línea del artículo. Por ejemplo: https://soporte.athento.com/hc/es/articles/360013056514--C%C3%B3mo-extraer-el-OCR-de-un-documento. En este artículo vemos cómo “extraer el OCR de un documento” es el tema central del artículo y aparece en el título y la primera línea del contenido de forma exacta. Tener en cuenta esta regla también en las traducciones. - Rótulos. En Zendesk, los rótulos funcionan como etiquetas que sirven para describir el contenido de un artículo. Consulta más información en https://support.zendesk.com/hc/es/articles/4408835056154-Uso-de-r%C3%B3tulos-en-los-art%C3%ADculos-del-centro-de-ayuda.
Comentarios
0 comentarios
Inicie sesión para dejar un comentario.