Si se le ha acusado de escribir un documento que se supone que debe instruir a alguien más sobre cómo hacer algo, la forma actual de hacerlo arroja más o menos los viejos métodos por la ventana.
1. Grandes cabeceras bombásticas
Notarás que los encabezados en PCMech, como el que está justo arriba de esta oración, son enormes. Esto se debe a que son más fáciles de ver, leer y saber en qué parte del documento se encuentra.
2. Menos palabras
Camino equivocado:
La siguiente documentación explica cómo usar y operar Fanny Whacker 2000.
Manera correcta:
Instrucciones sobre cómo usar Fanny Whacker 2000
Siempre recuerde esta frase cuando escriba documentación: VAYA AL PUNTO LO MÁS RÁPIDO POSIBLE.
3. Saltar referencias inútiles
Si la referencia no tiene nada que ver con la instrucción básica de lo que está intentando describir, como:
Para obtener más información sobre Turnip Twaddler de Fanny Whacker 2000, consulte el documento FU, subsección ID10T.
… no hagas eso.
4. Fecha. Siempre.
La fecha en que se escribió la documentación debe estar en el área de pie de página de cada página. Si es un documento electrónico, la fecha se muestra dos veces. Una vez al principio, una vez al final.
Puede escribir esto como "Última revisión (inserte la fecha aquí)".
5. Las advertencias siempre deben publicarse antes del punto de no devolución
Si hay algo en su documentación que podría dañar / destruir / borrar algo si se realiza incorrectamente, esta información debe colocarse directamente después de dicha instrucción, estar a la vista (es decir, en la misma página) y acentuada.
Ejemplo:
Paso 5. Limpieza de Fanny Whacker 2000
Las palas del FW2000 deben limpiarse suavemente con un paño suave no abrasivo.
ADVERTENCIA: Utilice únicamente solvente sin amoníaco para evitar que el FW2000 explote y provoque su muerte prematura.
En una nota final, una buena documentación no proviene de ser súper descriptivo sobre cada cosa posible imaginable. Lea su documentación y pregúntese, ¿se instruye correctamente? Si la respuesta es sí, la siguiente pregunta es, ¿da instrucciones rápidamente ? En caso afirmativo, la documentación es buena.
