Documentación
Documentation es la sección de un producto que reúne sus manuales, guías y fichas técnicas. Un gestor enumera los documentos que el producto necesita e indica qué debe tratar cada uno. Los autores los escriben como borradores, los revisores comprueban esos borradores y un documento aprobado se puede publicar para sus lectores. Esta página va desde la lista de documentos hasta el momento en que existe un borrador.
Qué contiene la sección Documentation
Cada producto tiene una única lista de documentos. A cada documento le corresponden cuatro cosas:
- El documento en sí: un tipo (por ejemplo, un manual de mantenimiento) y un título.
- Sus secciones: una lista numerada que indica qué debe tratar el documento.
- Sus borradores: las copias de trabajo de su contenido, llamadas Draft v1, Draft v2, etc. Un borrador se escribe en el editor y pasa por una revisión.
- Su documento aprobado: lo que existe una vez que se aprueba un borrador. Conserva versiones aprobadas numeradas (la interfaz las llama Revision) y se puede publicar.
La escritura en un borrador se describe en Borradores, el Asistente en Asistente, y la revisión, la aprobación y la publicación en Revisión y publicación.
Abrir la documentación de un producto
En Products, selecciona el producto y, a continuación, selecciona Documentation en la barra lateral. Se abre la página Documentation, que enumera los documentos del producto bajo Required documents (documentos necesarios).
Una persona con el rol Viewer no ve esta página: en su lugar, Documentation le muestra los documentos publicados del producto (consulta Leer un documento).
Leer la lista de documentos
Cada fila muestra el título del documento, una segunda línea y un estado. La segunda línea es:
- «5 of 6 sections ready» (5 de 6 secciones listas), mientras el borrador más reciente está en el estado Draft y el documento tiene al menos una sección obligatoria (Ver lo que todavía falta indica de qué borrador se toma el recuento);
- en los demás casos, la fecha de creación del borrador más reciente, por ejemplo «Created 26 Sep 2026»;
- el tipo del documento, cuando no tiene ningún borrador.
| Estado | Qué significa |
|---|---|
| Not generated | El documento todavía no tiene ni borrador ni documento aprobado. |
| Generating… | El Asistente está escribiendo un borrador. |
| Importing… | Se está convirtiendo un archivo PDF o Word en un borrador. |
| Draft | El borrador más reciente se está escribiendo. |
| In review | El borrador más reciente se ha enviado y está en manos de los revisores. |
| Changes requested | Un revisor ha devuelto el borrador más reciente para que se corrija. |
| Endorsed · awaiting approval | La revisión ha terminado y el borrador más reciente espera la aprobación. |
| Approved | El borrador más reciente está aprobado y el documento no está publicado. |
| Rejected | El borrador más reciente se ha rechazado y el documento no está publicado. |
| Published · Team | El documento aprobado está publicado para la audiencia Team: los miembros de tu organización que han iniciado sesión. |
| Published · Public | El documento aprobado está publicado para la audiencia Public: cualquier persona que tenga su enlace. |
Cuando hay un borrador más reciente que todavía se está escribiendo o revisando, es ese borrador el que determina el estado. En la imagen, la fila del Operating manual indica Draft porque se está escribiendo un borrador más reciente. La fila no muestra que el documento también está publicado para la audiencia Team: Document details (detalles del documento) muestra tanto los borradores como el estado de publicación del documento (consulta Document details: finalidad, imagen de portada y borradores). Los estados de la revisión se explican en Revisión y publicación.
En un producto que todavía no tiene ningún documento, la página muestra «No documents yet» (todavía no hay documentos) encima del botón New document.
Quién puede hacer qué
El rol que una persona tiene en la organización determina lo que puede hacer en Documentation. Los roles se asignan en la página Organización.
| Rol | En Documentation |
|---|---|
| Manager | Todo: añadir y eliminar documentos, definir y asignar secciones, escribir, revisar, aprobar y publicar. |
| Author | Escribir: iniciar y modificar borradores, usar el Asistente, comentar y enviar un borrador a revisión. |
| Reviewer | Escribir como un Author y, además, revisar, avalar, aprobar y publicar. |
| Viewer | Nada en Documentation. Un Viewer lee los documentos publicados. |
| Owner | Todo lo que puede hacer un Manager, en la documentación que ha iniciado (se explica más abajo). |
- La persona que abre por primera vez la sección Documentation de un producto gestiona la documentación de ese producto, aunque su rol sea Author o Reviewer: es quien la ha iniciado. Así es como el propietario de la organización, que aparece como Owner, obtiene sus derechos en ella. Un Viewer no puede iniciarla.
- En esta página, «un gestor» es una persona que gestiona la documentación del producto: un Manager o la persona que la abrió por primera vez.
- New document, el botón Document actions (acciones del documento), los tres puntos de una sección, Add section (añadir sección) y Suggest sections (sugerir secciones) siguen visibles, pero atenuados (en gris), para los Authors y los Reviewers. Su texto emergente dice «Only managers can change documents and their sections. Ask a manager in your organization.» (solo los gestores pueden modificar los documentos y sus secciones; pídeselo a un gestor de tu organización).
- Los demás controles de un gestor no se ofrecen a los Authors ni a los Reviewers: Owner (responsable) y Reviewer (revisor) muestran un nombre en lugar de una lista, el interruptor Required (obligatoria) aparece atenuado, y Assign across document (asignar en todo el documento) y los tres puntos de un borrador bajo Outputs (resultados) no se muestran.
- Cuando la organización no tiene ningún miembro con el rol Reviewer, un Manager ve Approve junto a Submit for review (enviar a revisión) y puede aprobar un borrador sin ronda de revisión.
Añadir un documento
Start from (punto de partida), en el cuadro de diálogo, solo se muestra cuando la sección Sources (fuentes) del producto contiene un archivo PDF o Word.
Añadir un documento
Un gestor añade cada documento que el producto necesita y después indica qué debe tratar.
- En Documentation, selecciona New document.
- En Type, elige la clase de documento.
- Si se muestra Start from, deja An empty document (un documento vacío).
- Comprueba el campo Title: al elegir un tipo, se rellena si estaba vacío.
- Selecciona Create.
Para una unidad de sobremesa que se entrega con un manual y un plan de mantenimiento, añade un Operation Manual y un Maintenance Manual.
Aparece el mensaje «Document created» y el documento nuevo se abre con «No sections yet».
Los tipos son:
- Maintenance Manual, User Manual, Operation Manual, Installation Manual, Troubleshooting Guide y Training Package;
- para software: Repository Overview, Architecture y API Reference.
El tipo determina de qué plantilla estándar de secciones puede partir el documento. El tipo y el título de un documento no se pueden cambiar después.
Convertir un archivo PDF o Word en un borrador
Un manual que ya existe como archivo PDF o Word (.docx) en la sección Sources del producto puede convertirse en el primer borrador de un documento. Si el archivo todavía no está en Sources, añádelo allí primero (consulta Productos).
Importar un archivo como borrador
Un gestor convierte un archivo PDF o Word del producto en un borrador que se puede modificar.
- En Documentation, selecciona New document.
- En Start from, elige el archivo bajo Import one of this product's files (importar uno de los archivos de este producto). El cuadro de diálogo pasa a llamarse Import document.
- En Type, elige la clase de documento.
- Comprueba el campo Title. Se rellena con el nombre del archivo si estaba vacío.
- Selecciona Import.
Aparece el mensaje «Importing document» y se abre el borrador nuevo. Se va rellenando mientras se convierte el archivo y, durante ese tiempo, el documento muestra Importing… en la lista.
New document es el mismo cuadro de diálogo, con An empty document en Start from y el botón Create.
Para un gestor, el mismo cuadro de diálogo también se abre desde Sources: selecciona los tres puntos al final de la fila del archivo (el botón llamado Actions for seguido del nombre del archivo) y después Use as draft (usar como borrador).
Si la importación no puede empezar, aparece el mensaje «Could not import document» (no se ha podido importar el documento) y no se añade ningún documento. Si la conversión falla después, el borrador muestra «Could not import the reference file» (no se ha podido importar el archivo de referencia) junto con el motivo.
Abrir un documento
Selecciona una fila de la lista. El documento se abre con su estado, sus secciones y los botones que inician y abren sus borradores.
De izquierda a derecha, los botones son New draft (nuevo borrador), Submit for review, Open draft (abrir el borrador) con la flecha Choose a draft (elegir un borrador) y el botón Document actions (tres puntos). New draft aparece cuando el documento tiene una sección o un borrador; Submit for review, mientras el borrador más reciente está en Draft o en Changes requested; Open draft, cuando el documento tiene un borrador; la flecha, cuando tiene más de uno.
El menú Document actions, abierto en la imagen, contiene Suggest sections, Use template (usar la plantilla) y Delete document (eliminar el documento). Cada opción se describe más abajo.
Indicar qué debe tratar un documento
Un documento nuevo no tiene secciones y muestra «No sections yet». Un gestor define las secciones de una de estas tres maneras, y puede combinarlas. En el documento vacío, las tres maneras son los enlaces use the standard template (usar la plantilla estándar) y add them yourself (añadirlas tú mismo) y el botón Suggest sections.
Partir de la plantilla estándar
Añadir las secciones estándar
Cada tipo de documento tiene una lista estándar de capítulos y secciones de la que partir.
- Abre el documento.
- En un documento sin secciones, selecciona use the standard template.
- Lee la lista de capítulos y secciones en el cuadro de diálogo.
- Selecciona Add sections (añadir las secciones), o Discard (descartar) para dejar el documento como está.
Aparece el mensaje «Sections added» y las secciones se enumeran bajo Sections. Después puedes modificar o quitar cualquiera de ellas.
En un documento que ya tiene secciones, la plantilla está en el menú Document actions: Use template. El cuadro de diálogo ofrece entonces Add to existing, que añade las secciones de la plantilla a las del documento, y Replace existing, que las sustituye.
Añadir una sección a mano
Añadir una sección
Un gestor añade una sección, o un capítulo que agrupa secciones.
- Abre el documento.
- Selecciona Add section bajo la lista, o add them yourself en un documento sin secciones.
- Introduce un título en Title. Una sección sin título recibe el nombre de su tipo de contenido.
- En Content type (tipo de contenido), elige qué clase de contenido incluye la sección.
- Deja Required activado, salvo que la sección sea opcional y no deba contar en la barra situada encima de la lista.
- Para crear un capítulo en lugar de una sección, activa Chapter with sub-sections (capítulo con subsecciones).
- Selecciona Add.
El formulario se cierra y la sección nueva aparece al final de la lista. Para indicar qué debe tratar, ábrela y selecciona Edit section (modificar la sección): consulta la sección «Modificar, mover o quitar una sección», más abajo en esta página.
| Tipo de contenido | Elígelo para |
|---|---|
| Procedure (step-by-step) | Una tarea que la persona que mantiene el producto realiza paso a paso: desmontaje, instalación, reparación, mantenimiento. |
| Description | Cómo funciona el producto y sus datos: descripción general, datos técnicos, seguridad, introducción. |
| Fault isolation | Localizar y reparar una avería: resolución de problemas, códigos de avería. |
| Parts list | Piezas: repuestos, herramientas y consumibles. |
| Crew / operating | Una tarea de la persona que maneja el producto: instrucciones de uso, mandos. |
| Process | Un calendario o un plan: intervalos de mantenimiento, retirada del servicio. |
En este formulario, Advanced muestra dos ajustes más, Weight (peso) y Criticality (criticidad); el formulario para modificar una sección añade un tercero, Section number (número de sección). Los tres se describen en Modificar, mover o quitar una sección.
Dejar que el Asistente proponga las secciones
Suggest sections, en un documento sin secciones y en el menú Document actions, abre el Asistente con una petición para que proponga las secciones de este documento. Consulta Asistente.
Capítulos y subsecciones
Un capítulo es un título que agrupa secciones. No tiene contenido propio: su estado cuenta las secciones que contiene, por ejemplo «0 of 2 ready». Las secciones de un capítulo se numeran 1.1, 1.2, etc.
Selecciona un capítulo para abrirlo. Primero se enumeran sus secciones y después la fila Chapter settings (ajustes del capítulo), que contiene Owner, Reviewer, el interruptor Required y los tres puntos del capítulo. Para añadir una sección dentro de un capítulo, o dentro de otra sección, selecciona sus tres puntos y después Add sub-item (añadir subelemento).
Modificar, mover o quitar una sección
Selecciona una sección para abrirla. Una sección abierta muestra What it must cover (qué debe tratar), su Owner, su Reviewer, el interruptor Required y una nota sobre lo que el documento ya contiene para ella. Al desactivar Required, la sección sigue en la lista, pero no cuenta en «5 of 6 sections ready».
Los tres puntos de la parte inferior derecha de una sección abierta son un botón, llamado Actions for seguido del título de la sección. Ahí encuentra un gestor el resto: Edit section, Add sub-item, Move up (subir), Move down (bajar) y Remove section (quitar la sección).
Modificar una sección
Un gestor cambia el título de una sección, lo que debe tratar y su tipo de contenido.
- Abre la sección.
- Selecciona los tres puntos de la parte inferior derecha de la sección y después Edit section.
- Cambia el título, el texto bajo What it must cover y el Content type.
- Selecciona Save.
La sección muestra el título y el texto nuevos. Un cambio de Owner o de Reviewer en este formulario se guarda al instante, sin Save.
En Advanced, el Weight (de 1 a 5) indica cuánto cuenta la sección en el porcentaje de Section coverage (cobertura de las secciones; se explica más abajo). Section number y Criticality se guardan con la sección. La lista no los muestra: numera las secciones según su orden.
Las demás entradas del menú:
- Move up y Move down cambian el orden. Move up aparece atenuado en la primera sección, Move down en la última, y ambos mientras Gaps only (solo lo que falta) está activado.
Una sección también se puede arrastrar por su fila hasta su nuevo lugar. Se mueve entre las secciones de su propio capítulo, o entre las entradas de primer nivel si se trata de un capítulo o de una sección que no está en ningún capítulo; no se puede soltar en otro capítulo. El arrastre está desactivado mientras Gaps only está activado.
- Remove section pide confirmación («This cannot be undone.», es decir, no se puede deshacer) y, al seleccionar Remove, quita la sección. Al quitar un capítulo o una sección que tiene subelementos, estos también se quitan.
Asignar un responsable y un revisor
Un gestor asigna a cada sección un Owner, que es el responsable de escribirla, y un Reviewer, que la comprueba. La asignación no bloquea la sección: los demás Authors, Reviewers y gestores pueden seguir escribiendo en ella.
Abre la sección y elige una persona en Owner y en Reviewer. La elección se guarda al instante y se notifica a la persona. Elige Unassigned (sin asignar) para dejar el campo vacío.
- La lista Owner incluye a los Managers, Authors y Reviewers de la organización y a la persona que inició la documentación del producto; la lista Reviewer, a los Reviewers, a los Managers y a esa misma persona.
- En un capítulo, en Chapter settings, la elección se aplica a todas las secciones del capítulo. El campo muestra «Multiple people» (varias personas) cuando sus secciones tienen responsables distintos.
- Assign across document, bajo la lista, abre una lista Owner y una lista Reviewer para todo el documento. Al elegir ahí una persona, se le asignan todas las secciones del documento, incluidas las que tenían a otra persona. Unassigned las deja todas sin asignar.
Las secciones de las que una persona es responsable o revisora aparecen en su página Tus tareas.
Ver lo que todavía falta
Cada sección tiene un estado. El estado se mide en un solo borrador: el último borrador aprobado del documento, si lo tiene; si no, su borrador más reciente. Por eso, mientras se escribe un borrador nuevo de un documento aprobado, los estados siguen describiendo el borrador aprobado.
| Estado de una sección | Qué significa |
|---|---|
| Ready | Ese borrador tiene una sección para ella con contenido: texto, una tabla o una imagen. |
| Partial | Ese borrador tiene una sección para ella, y la sección sigue vacía. |
| Missing | Ese borrador no tiene ninguna sección para ella. |
- La barra situada encima de la lista cuenta las secciones obligatorias que están listas: «5 of 6 sections ready».
- Gaps only muestra solo las secciones que no están listas. Cuando no hay ninguna, la lista muestra «All sections are ready. There are no gaps to show.» (todas las secciones están listas; no hay nada pendiente que mostrar).
- Selecciona la barra para abrir Section coverage. Muestra un porcentaje, en el que una sección Partial cuenta la mitad y cada sección cuenta según su Weight, y, bajo Needs work (por completar), cada sección que no está lista, con su grado de avance y una nota.
Los mismos tres estados llegan al responsable de una sección como indicación en la página Tus tareas. El Outline de un borrador tiene sus propias notas, Not written yet (aún sin redactar) e Incomplete (incompleta): son notas que el Asistente dejó en ese borrador concreto, no los estados descritos aquí, de modo que una sección puede estar Ready en esta lista e Incomplete en ese Outline. Consulta Revisión y publicación.
Iniciar o abrir un borrador
Los gestores, los Authors y los Reviewers pueden iniciar un borrador cuando el documento tiene una sección o un borrador.
Iniciar un borrador
Un borrador empieza vacío a partir de las secciones, como copia de otro borrador o escrito por el Asistente.
- Abre el documento y selecciona New draft.
- En Start from, deja Sections o elige un borrador bajo Copy a draft (copiar un borrador).
- Selecciona Create, o Generate para que el Asistente escriba el borrador.
Con Create, el borrador se abre: si parte de Sections, con todas las secciones del documento dispuestas, vacías; si parte de un borrador, como copia de ese borrador.
Generate transmite al Asistente lo que escribas en Instructions for Generate (optional). El borrador se abre en cuanto existe y se va rellenando mientras el Asistente escribe, y el documento muestra Generating… en la lista. Si el borrador no se puede escribir, aparece el mensaje «Could not generate draft» (no se ha podido generar el borrador). Consulta Asistente.
Abrir un borrador
Open draft abre el borrador más reciente. La flecha Choose a draft, a su lado, enumera todos los borradores, del más reciente al más antiguo, con su estado y su fecha de creación. Draft v1 es el más antiguo; el más reciente lleva la palabra «Latest». El trabajo en el borrador se describe en Borradores y en Tablas, imágenes y vistas 3D.
Document details: finalidad, imagen de portada y borradores
Debajo de la lista de secciones, selecciona el enlace Document details.
- Purpose and scope (finalidad y alcance): el objetivo del documento. Se imprime en la portada del PDF del documento, cuya maquetación define una plantilla de exportación (consulta Plantillas de exportación).
- La imagen de portada: la predeterminada es la imagen del producto cuando este tiene un modelo 3D; si no, la imagen definida en la plantilla de exportación. Upload la sustituye por una imagen tuya (el botón pasa a llamarse Replace), Remove la quita y Use default recupera la predeterminada. La línea que hay debajo indica Custom image (imagen personalizada), Default image (imagen predeterminada) o No image (sin imagen).
- Outputs: los borradores del documento, del más reciente al más antiguo, cada uno con su estado, y después el Approved document (documento aprobado) con su número de versiones aprobadas. Selecciona un borrador para abrirlo en el editor. Selecciona Approved document para abrir el documento aprobado y sus versiones aprobadas (consulta Revisión y publicación). Cuando el documento está publicado, el icono del final de esa fila lo abre tal como lo ven los lectores.
Los gestores, los Authors y los Reviewers pueden cambiar la finalidad y la imagen de portada. Ninguna de las dos aparece en el cuadro de diálogo, que entonces solo muestra Outputs, cuando la plantilla de documento con la que se componen tus borradores (la predeterminada de la organización, salvo que hayas elegido otra en la pestaña Preview de un borrador) tiene desactivado Purpose per document (finalidad por documento; consulta Plantillas de exportación).
Enviar a revisión el borrador más reciente
Submit for review, en la parte superior del documento, envía a revisión el borrador más reciente sin abrirlo: aparece el mensaje «Submitted for review» y el estado pasa a In review. Consulta Revisión y publicación.
Eliminar un borrador o un documento
Solo un gestor puede eliminar. Los tres puntos al final de la fila de un borrador, bajo Outputs, son un botón, llamado Actions for draft seguido del título del borrador. Un borrador aprobado no se puede eliminar: su fila no tiene tres puntos.
Eliminar un borrador
Un borrador que no está aprobado se puede eliminar junto con su contenido.
- Abre el documento y selecciona Document details.
- En Outputs, selecciona los tres puntos al final de la fila del borrador.
- Selecciona Delete draft.
- En Delete draft?, selecciona Delete.
Aparece el mensaje «Draft deleted». El borrador y su contenido se eliminan definitivamente.
Eliminar un documento no retira su publicación. Un documento publicado sigue disponible para sus lectores: para que deje de estarlo, retira primero su publicación (consulta Revisión y publicación).
Eliminar un documento
Al eliminar un documento se eliminan sus secciones y todos los borradores que no están aprobados.
- Abre el documento.
- Selecciona el botón Document actions (tres puntos), arriba a la derecha.
- Selecciona Delete document.
- En Delete document?, selecciona Delete.
Aparece el mensaje «Document deleted» y se abre la lista. Los borradores aprobados se conservan: aparecen bajo Unfiled drafts (borradores sin clasificar), al final de la lista, donde se pueden seguir abriendo.
Delete document no se ofrece mientras se está generando o importando un borrador del documento.
Comprobar dónde se usa un archivo o un procedimiento
Un documento puede citar un archivo del producto e incrustar un procedimiento. Antes de eliminar un archivo o un esquema de Sources, la confirmación muestra el informe Where this is used (dónde se usa). Antes de eliminar un procedimiento, indica en una frase qué documentos lo incrustan. La confirmación aparece en imagen en Productos para un archivo y en Procedimientos para un procedimiento.
- El informe agrupa lo que usa el elemento bajo Procedures, Published documents y Drafts. Cada tarjeta nombra un documento, un borrador o un procedimiento y los lugares correspondientes.
- Open document, Open section, Open draft y Open procedure abren ese lugar en una pestaña nueva, para que puedas corregirlo antes.
- Why is this listed? (¿por qué aparece aquí?) muestra el motivo de una línea.
- Cuando nada usa el elemento, el informe muestra «No procedure, document or draft uses this.» (ningún procedimiento, documento ni borrador lo usa).
Después, Delete file o Delete procedure elimina el elemento. Los documentos y los borradores conservan su texto, pero una cita pierde el archivo en el que se apoya.
Qué más lee el Asistente
El Asistente escribe a partir de las fuentes del producto. En la sección Sources se le pueden añadir dos cosas más: Link a product (vincular un producto), bajo Linked products, le permite leer también las fuentes de otro producto, por ejemplo un modelo anterior, y Connect repository (conectar un repositorio), bajo Code, conecta un repositorio de GitHub o GitLab, que el Asistente solo lee. Cuando hay un producto vinculado, la frase que hay bajo el título de la página Documentation termina con «The Assistant also sees 1 linked product.» (el Asistente también ve 1 producto vinculado).