Estamos trabajando en un manual de software con varios capítulos y temas y, hasta ahora, estos son en su mayoría independientes. Esto significa que tenemos un capítulo dedicado a la "conectividad" y no mencionamos la conectividad en otros lugares, un capítulo dedicado a las "actualizaciones de software" y no mencionamos las actualizaciones en otros lugares, etc. Se entiende la idea.
Pero ahora tenemos una nueva funcionalidad de software que afecta a diferentes temas del manual (por ejemplo, los temas A, C y G). Cada uno de estos temas es independiente y está aislado de los demás, pero se ve afectado de manera diferente por esta nueva funcionalidad.
La pregunta es, ¿cuál sería el mejor enfoque para leer sobre esta nueva funcionalidad?:
Vemos ventajas y desventajas en ambos. En ( 1 ) tenemos todo en un solo lugar, lo que facilita las cosas a largo plazo, pero H sería un tema de cosas dispares. En ( 2 ) proporcionamos la información en el tema mismo, donde más se necesita, pero esto es difícil de mantener a largo plazo.
gracias, jorge
Depende, pero probablemente desee el enfoque distribuido donde el capítulo sobre X le dice todo lo que necesita saber sobre X, incluso si algo de eso solo es relevante si está usando la función Y. Sin embargo, si Y es un caso de esquina o implica una gran cantidad de cambios en varias otras características, es mejor que recopile todo sobre Y en un solo lugar y lo vincule desde todos los demás capítulos que toca . Sin embargo, no lo ponga en su propio capítulo y no diga nada en los demás; eso puede generar sorpresas cuando los usuarios que saltaron directamente a X luego descubren que deberían haber hecho X' porque están usando Y.
Además de esto, un enfoque que usa mi equipo es tener una sección del conjunto de documentos (un paquete HTML de todos los documentos individuales) que describe las nuevas características de esta versión. Cada función nueva recibe una descripción de alto nivel de lo que es y cuándo puede usarla, y termina con enlaces a los lugares relevantes en los documentos "principales". Las personas interesadas en la "nueva función Y" pueden ir allí para acceder fácilmente a la información (a través de enlaces), pero el contenido principal está en los otros documentos.
¿Cómo leen y usan sus usuarios el manual?
Si lo usan como un libro de texto , donde el 95 % de los lectores empiezan por el principio y avanzan hasta el final de manera lineal, entonces pongan toda la información nueva en un capítulo al final.
Si lo usan como un libro de referencia , por lo que los capítulos se leen desordenadamente, individualmente o ni siquiera en su totalidad porque la persona está buscando una característica, entonces necesita el método dispar.
Para usar el ejemplo de SaberWriter, si todo lo que necesito hacer es buscar cómo crear menús en HTML, sería útil tener al menos una nota que diga que podría hacer lo mismo con CSS o incluso más fácilmente con JavaScript, un breve resumen del proceso y luego una referencia a una explicación más extensa en los capítulos de CSS y JavaScript.
Creo que ya tienes tu respuesta de verdad. Explique cada tema en su propio capítulo a medida que los tenga, luego cree un nuevo capítulo que explique esta característica adicional que altera el comportamiento de estos otros elementos.
Usar capas de explicación Crear capas de comprensión
Dividirlo de esta manera y explicar los puntos fundamentales que desea que su lector comprenda primero creará capas de comprensión que luego harán que los materiales posteriores sean más fáciles de comprender.
Usemos HTML, CSS y JavaScript como ejemplo.
Capítulo 1: ¿Qué es HTML?
HTML significa lenguaje de marcado de hipertexto... ...
HTML es la estructura de su documento. Nos permite crear la estructura del DOM (Document Object Model) La etiqueta es un tipo de bloque de elemento HTML. ...
Capítulo 2: ¿Qué es CSS?
CSS es un acrónimo que significa hojas de estilo en cascada... ...
Para diseñar todas las etiquetas <DIV> con class="book" <DIV> class="book") podemos hacer algo como lo siguiente:
#book {color:red; padding: 2px 2px 2px 2px;}Capítulo 3: ¿Qué es JavaScript?
JavaScript se puede utilizar para manipular el DOM, la estructura del HTML:
<div id='extra'>test</div> document.getElementById("extra").appendChild(node);JavaScript también se puede usar para alterar el estilo de un elemento DOM en particular.
document.getElementById("p2").style.color = "blue";
La base es sólida
Cuando sus lectores lleguen a JavaScript (un tema más avanzado que requiere la comprensión de la información anterior), podrán agregar esta nueva capa de comprensión porque ha creado una base para ellos.
Espero que esto ayude. Buena suerte con tu proyecto.
usuario9995
Mónica Celio