¿Cómo empezar un libro técnico?

Dado que usted es un desarrollador de software, lo animo a que piense en el libro de la misma manera que piensa en una aplicación importante. Usted (probablemente) no solo comienza a escribir código; haces un análisis de requisitos, tal vez un análisis de casos de uso (por favor, no destruyas mis sueños :-)), un diseño de alto nivel... y luego, si eres como la mayoría de nosotros, empiezas a implementar, descubres algunas cosas que puedes mejorar y otras cosas en las que no pensaste, e iterar. Esto no es tan diferente aparte de que estás produciendo texto en lugar de código.

Como dice esta respuesta , un primer paso debe ser una lluvia de ideas sobre el contenido y comenzar a organizarlo en un esquema. Este esquema no está grabado en piedra; Piense en ello como si estuviera echado en gelatina. Pero necesitas un punto de partida. Probablemente terminará con una lista de temas específicos (¿capítulos? ¿secciones?), junto con una introducción. Salta la introducción. Las introducciones son difíciles; Guárdalo para después. En su lugar, elija uno de los temas concretos que ha identificado y comience a escribirlo de forma aislada. Piense en ello como una publicación de blog sobre esteroides o una sola conferencia en una clase: sabe que habrá otro contexto y que tendrá que agregar algo de tejido conectivo, pero ¿qué necesita para transmitir esto ?¿tema? Escribe eso. No pulir todavía; solo escribe las cosas de la manera más coherente que puedas. Luego haz otro. Luego uno más.

Después de que haya hecho algunos, comenzará a ver dónde tiene dependencias cruzadas, qué preguntas no consideró y qué patrones comienzan a surgir en su escritura (como cómo y cuánto habla sobre ejemplos de código ). Genial: ahora puede pausar la escritura, evaluar dónde se encuentra, refactorizar, tal vez tirar algunas cosas y continuar con una mejor idea de hacia dónde se dirige. Los libros toman tiempo y tienden a dar sorpresas; no asuma que su primer bosquejo sobrevivirá al contacto con la realidad. Pero tienes que empezar en alguna parte , así que elige algo y vete.

He estado en el mundo del software, tanto como escritor técnico como programador, durante unos cuantos años. Esta respuesta se basa en mi experiencia y observaciones del campo. Ah, y todavía escribo mis presentaciones al final.

El primer paso que siempre recomendaría para cualquier escritura, pero en particular para la escritura técnica, es hacer una lluvia de ideas y esbozar. Comience simplemente compilando una lista de temas que desea cubrir. Una vez que tenga esa lista, comience a ponerlos en un orden lógico. Cuando comience a ponerlos en orden, es probable que identifique temas de transición y temas de apoyo que no se le ocurrieron mientras estaba haciendo una lluvia de ideas.

Trabajo en una tienda de desarrollo de software y, como consejo, no asuma que sus lectores conocen ciertos hechos o puntos. Si su intención es crear una guía para principiantes, asegúrese de cubrir los conceptos básicos. Tengo problemas con algunos desarrolladores que asumen que las personas saben algunos de los conceptos básicos de la programación solo porque es algo natural para ellos (de ninguna manera son los desarrolladores las únicas personas que pasan por alto los conceptos básicos de su experiencia).

Buena suerte.

Cuando haga el esquema, piense también en el alcance del libro: ¿qué esperaría de un libro así? ¿Qué preferirías no ver? Por ejemplo, si este es un libro sobre técnicas e hilos avanzados de C++, probablemente no quiera explicar qué es una clase. Piensa en tu público objetivo.