Como redactar un buen HOWTO

Los CÓMOs (HOWTOs) son documentos informales, generalmente cortos, que describen cómo cumplir con una cierta tarea (wikipedia) Pues estaba navengando por Internet, buscando ideas de como mejorar Simutrans como proyecto de código abierto cuando me encontré con este artículo que describe como hacer un buen CÓMO (suena raro, ya lo sé) Paso a traducirlo, porque creo que es muy interesante y fácil de aplicar

Leer más...


1.Intenta que sean cortos

• Se específico. Se supone que los CÓMOs son pequeñas guías acerca de tareas específicas, de manera que no menciones otros temas, incluso si estan relacionados. Esto no lleva al siguiente punto


• Deja los detalles irrelevantes para los apendices u otros documentos. Los detalles tienden a distraer al lector.


• Divide el documento en varios ficheros, para facilitar su lectura en caso de que vaya a ser online

2.Haz que sea de fácil lectura

• Usa lenguaje informal. Imagina que el lector está frente a tí.


• Destaca la información importante. Mucha gente echa un vistazo rápido al documento buscando determinada información


• Resume y clasifica. Esto no sol ayuda al lector a encontrar lo que busca más rapidamente, sino que también te ayuda a organizar las ideas mientras que estas escribiendo


• Usa listas y secciones. Esto ayuda a conseguir el anterior objetivo. El como entero puede ser una simple lista si estás desarrollando un tema sencillo (como este)

3.Haz uso de recursos visuales

• Usa imágenes o vídeos. Pueden ahorrarte mucho texto, pero úsalos con moderación porque hay mucha gente que usa conexiones lentas. Sin embargo, los videos COMOs pueden ser la mejor elección en el caso de tareas complejas

4.Hazlo simple. Este es tal vez el punto más importante, y condensa a todos los demás. Después de todo, se supone que los COMOs son para aclarar cosas o conceptos ¿no?

• Usa términos técnicos solo cuando sea necesario


• Crea un glosario de términos técnicos o enlaza con una artículo de un wiki donde se expliquen.