Estoy escribiendo una documentación técnica sobre un producto. Ahora el problema es que hay muchos conceptos interrelacionados e interdependientes. Estoy confundido sobre cómo ponerlos en orden. Quiero decir, si hablo del primer concepto, necesita un poco de comprensión del segundo tema y si hablo del segundo tema, necesita la comprensión del primero.
Existen dos enfoques generales, según la cantidad de detalles que necesite del concepto "otro".
Si no necesita mucho, escriba sobre el tema A, y cuando llegue la primera interacción con B, agregue una oración entre paréntesis, una nota destacada o una nota al pie (según su guía de estilo) que describa el otro concepto y señale su principal documentación. Por ejemplo:
Para configurar una suscripción, haga (bla, bla, bla) y especifique la URL de devolución de llamada. (Una devolución de llamada es un servicio que escribe que este servicio llamará con datos actualizados. Consulte la Sección X).
Si los temas o sus interconexiones son más complicados, el otro enfoque es escribir una breve descripción general que presente todos los conceptos. Piense en esto como una documentación de amplitud. La descripción general debe apuntar a la documentación más detallada sobre cada tema.
Esto es muy común en ciertos tipos de proyectos. Puede intentar comenzar presentando una estructura de árbol (no necesariamente un diagrama) para obtener una imagen general rápida de los elementos y su interdependencia de un vistazo: una vista aérea, más o menos.
Solo recuerde seguir la misma lógica de relación al establecer los elementos individuales en la discusión principal. Piense en ello como si presentara una tabla de contenido primero y luego los capítulos en el mismo orden, solo que aquí el TOC no es lineal.
Háganos saber cómo ve esta opción.
Creo que esta es una situación común. La mayoría de los sistemas tienen diferentes partes que interactúan entre sí y con la palabra externa.
Las mejores presentaciones/documentaciones que he visto comienzan describiendo primero el entorno en el que evoluciona el sistema, con una descripción general de alto nivel del propio sistema. Luego presentan rápidamente uno o dos usos comunes y cómo se tratan.
Creo que probablemente deberías seguir el mismo patrón.
Y luego continúa describiendo cada parte individualmente.
La única forma de no tener referencias hacia adelante es construir todo desde abajo. Así que empiezas con un glosario, definiendo los términos que vas a usar. En algunos casos, estos pueden tener referencias cruzadas entre sí, ya que todos estarán en la misma área. Luego hace sus definiciones: los procesos básicos que están involucrados, nuevamente con alguna referencia cruzada si es necesario. También puede hacer referencias de tipo "ver también" más adelante en el manual, por lo que al referirse a la definición de un proceso de wizzlet, puede decir "para obtener detalles sobre cómo iniciar y configurar un proceso de wizzlet, consulte la sección 26 a continuación). Esto significa que las personas que quieran referirse a esto por una necesidad específica pueden seguirlos, pero también se puede leer ignorando esto.
Con suerte, en este punto, podrá escribir la mayor parte del texto, haciendo referencia hacia atrás pero no hacia adelante (aunque también puede ser útil ver más referencias; estas son para proporcionar enlaces que no es necesario seguir para entender).
En tu caso concreto, definirías los principios del tema 1 y el tema 2, con posibles referencias cruzadas si fuera necesario, aunque si puedes evitarlas, mejor. La interacción detallada de estos dos se trata en el texto principal.
Entonces, si necesita definir Cyclone Bigit, que se crea a partir de un Convex Waddle, y el convex waddle solo tiene un significado como el progenitor de Cycle Bigit, entonces primero define los significados: ¿qué es un Bigit? ¿Qué es un Waddle? Luego defines el Cyclone Bigit, independientemente de cómo se genera o para qué sirve. También define, independientemente del contexto, el Convex Waddle.
Una vez que haya definido ambos, de una manera que sea insuficiente para usarlos, pero suficiente para apreciar su referencia potencial, puede explicar cómo toma y define un Waddle y lo convierte en su Bigit. Con suerte, alguien que lo lea completo comprenderá lentamente todo el proceso y comprenderá lo que se necesita al final.
Cada vez que estoy en esta situación aprovecho lo siguiente:
Uso LaTeX y hacer glosarios y referencias cruzadas es muy fácil.
Página de Cliff Hangerson