Markdown: se aprende en diez minutos y dura toda la vida
Wiki.js permite escribir de varias formas, pero la principal es Markdown: escribes texto normal y le pones unas marcas para indicar qué es título, qué va en negrita y qué es una lista.
Vale la pena aprenderlo aunque nunca vuelvas a usar Wiki.js: es el mismo formato de GitHub, de miles de herramientas y de casi toda la documentación técnica que vas a leer.
# Titulo principal
## Un apartado
### Un subapartado
Texto normal. **Esto va en negrita** y *esto en cursiva*.
- Una lista
- Otro elemento
1. Una lista numerada
2. Segundo paso
[Un enlace](/otra/pagina)
`un comando o un nombre de campo`
> Una nota o una advertencia
| Columna A | Columna B |
|-----------|-----------|
| dato | dato |Con esto cubres el 95% de lo que vas a escribir. El resto se busca el dia que haga falta.
Wiki.js muestra el resultado mientras escribes, así que no hace falta memorizar nada: se prueba y se ve. Y si algo no te sale, tiene botones para lo habitual - negrita, listas, enlaces -, igual que un procesador de texto.
Ahora lo difícil: escribir para que otro entienda
El formato se aprende en diez minutos. Lo que cuesta es escribir un procedimiento que alguien pueda seguir sin ti al lado.
Y ahí el problema es siempre el mismo: escribes desde lo que ya sabes, y das por obvias tres cosas que quien lee no conoce.
Empieza diciendo para qué sirve y cuándo se usa
Dos líneas antes del procedimiento: «Esta página explica cómo emitir una factura a un cliente ya registrado. Si el cliente es nuevo, ve primero a Registrar un cliente.»
Evita que alguien siga cinco pasos para descubrir que no era su caso.
Di qué hace falta antes de empezar
Accesos, datos, permisos, archivos. Lo peor que le puede pasar a quien sigue un procedimiento es descubrir en el paso 6 que necesitaba un permiso que tarda dos días.
Un paso, una acción
«Abre el sistema, entra a Facturación, selecciona el cliente y dale a Nuevo» son cuatro pasos, no uno. Numerados, para poder decir «me quedé en el 3».
Escribe lo que se ve en pantalla
«Haz clic en Guardar cambios», no «guarda». Con el texto exacto del botón, entre comillas o en negrita.
Di cómo saber que salió bien
«Si funcionó, verás el número de factura en pantalla.» Sin eso, quien lo sigue no sabe si terminó o si algo falló en silencio.
Anota lo que suele salir mal
Al final, un apartado con los dos o tres errores frecuentes y su solución. Es la parte más consultada de cualquier procedimiento.
La prueba de fuego: dásela a alguien que no sepa hacerlo y no le ayudes. Que lo intente solo, con tu página delante. Cada vez que tenga que preguntarte algo, ahí falta un paso.
Es incómodo y es la única forma real de saber si tu documentación sirve.
Escribe el porqué, no solo el cómo
Lo que más valor tiene y menos se escribe. Un procedimiento dice qué hacer; el porqué dice qué pasa si lo cambias.
SOLO EL COMO:
4. Guarda el archivo en la carpeta del mes.
CON EL PORQUE:
4. Guarda el archivo en la carpeta del mes.
La carpeta se llama con el formato AAAA-MM porque asi se ordena
sola. Si le pones "Septiembre", queda entre Octubre y Agosto.El segundo evita que alguien "mejore" el sistema el ano que viene y rompa el orden sin entender por que estaba asi.
Imágenes: pocas y bien elegidas
Una captura de pantalla ayuda cuando el paso es «dónde está el botón». Pero tiene un coste: las capturas caducan. Cambia la interfaz del sistema y tu documentación queda desactualizada sin que nadie la haya tocado.
Usa capturas para lo que no cambia con frecuencia y descríbelo también en texto. Así, cuando la imagen envejezca, las palabras siguen sirviendo.
Compruébalo tú mismo
Escribiste un procedimiento. ¿Cuál es la mejor forma de saber si sirve?
¿Por qué conviene describir en texto lo que muestra una captura de pantalla?
Siguiente: Permisos: quién ve qué y quién puede editar
Continuar ← La estructura: que la información se encuentre