Made in DeveloperHub
Con DeveloperHub, puedes versionar tus documentaciones. La versión predeterminada se llama v1.0, y depende de ti definir cómo nombrar tus versiones. El versionado semántico no es obligatorio, por lo que puedes usar palabras como "beta", "alpha" y "latest" junto con números de versión reales.
El versionado es muy potente. Cuando las páginas están enlazadas dentro de una versión y esa versión se clona, todos los enlaces de las páginas se actualizan para que coincidan con la nueva versión.
Administrar versiones
La mayoría de las acciones de versiones están en la página Manage Versions. Para abrirla:
En la navegación superior del editor, haz clic en el menú de versiones.
Haz clic en el engranaje de ajustes .
La lista de la izquierda muestra todas las versiones del proyecto. Selecciona una versión para ver y editar sus ajustes a la derecha.
Crear versiones
Para crear una nueva versión:
Abre el menú de versiones en la navegación superior.
Haz clic en + New version.
Asígnale un nombre.
Elige Clone from current version para copiar toda la documentación y las páginas de la versión actual, o Create from scratch para empezar con una versión vacía.
Cuando clonas una versión, toda la documentación, referencia de API y páginas de la versión de origen se copian en la nueva versión.
Clonar a través de la API
También puedes clonar una versión a través de la API, lo cual es útil para crear una nueva versión desde un flujo de publicación. Copia el mismo contenido que el editor y deja la nueva versión sin publicar, de modo que puedas revisarla antes de que se publique. La clave de API necesita el permiso version.edit.
Publicar el clon es una llamada aparte que requiere el permiso version.publish. Todo lo que hay dentro de una versión clonada comienza sin publicar, así que primero publica una documentación o una referencia de API en ella; de lo contrario, se rechaza la publicación de la versión.
Publicar versiones
Por defecto, las versiones no están publicadas. Para publicar (o despublicar):
Abre el menú de versiones en la navegación superior y selecciona la versión.
En Manage Versions, activa Published en la tarjeta Visibility o usa el botón Publish / Unpublish del encabezado.
Cuando se publica una versión, los lectores solo podrán ver la documentación y las referencias de API publicadas de esa versión. Despublicar una versión hace que la versión y todo su contenido dejen de ser visibles para los lectores, pero no modifica el estado de publicación de su documentación ni de sus referencias de API.
Las versiones sin publicar muestran una etiqueta Unpublished en el menú de versiones y en la lista de Manage Versions.
Eliminar versiones
Para eliminar una versión:
Abre Manage Versions.
Selecciona la versión que quieres eliminar.
En la tarjeta Danger zone, haz clic en Delete version.
Confirma la eliminación.
Una vez eliminada una versión, no se puede recuperar.
Ordenar versiones
Para cambiar el orden de una versión en el selector:
Abre Manage Versions.
Arrastra la versión desde el control .
Suelta la versión en el lugar deseado.
Si la versión está en primer lugar y está publicada, será la versión predeterminada que se cargue para tus lectores.
La versión predeterminada no muestra su slug en los enlaces de las páginas publicadas; por ejemplo, si la versión 1.0 fuera la predeterminada de este proyecto de documentación:
https://docs.developerhub.io/support-center/managing-versions significaría implícitamente que debe cargarse la versión predeterminada, que es la versión 1.0. Usar https://docs.developerhub.io/v1.0/support-center/managing-versions daría el mismo resultado.
Ocultar el selector de versiones
Si tu proyecto solo tiene una versión, o prefieres que los lectores no cambien de versión por sí mismos, puedes quitar el menú desplegable de versiones de la navegación superior del lector.
Para ocultarlo:
Abre Project Settings y luego el panel Customisation.
En la tarjeta Look and feel, activa Hide version picker.
La vista previa del lector en la parte superior del panel se actualiza al activar la opción, así que puedes ver la navegación superior sin el selector antes de guardar.
Ocultar el selector solo elimina el menú desplegable. Las versiones no se tocan: su estado de publicación se mantiene y los lectores aún pueden abrir cualquier versión publicada mediante un enlace que incluya su slug, como https://docs.developerhub.io/v1.0/support-center/managing-versions.
Llevar a los lectores a la nueva versión
Si tus lectores han guardado como marcadores páginas de versiones anteriores, o no saben que tu documentación tiene versiones, quizá quieras avisarles con un banner en la parte superior de la página de que existe una versión más reciente. Puedes hacerlo con un ajuste avanzado estableciendo warnings.oldVersion en true.
Bloquear versiones
Las versiones se pueden bloquear cuando ya no deban poder editarse su documentación y sus referencias de API. Cuando una versión está bloqueada, la documentación y las referencias de API no se pueden:
Crear.
Editar.
Eliminar.
Publicar.
Esto también se aplica a los cambios realizados mediante la API.
Para bloquear o desbloquear una versión:
Abre Manage Versions.
Selecciona la versión.
En la tarjeta Visibility, activa Locked.
Una etiqueta Locked aparece en el menú de versiones y en la lista de Manage Versions. Los botones Save draft y Publish de las páginas se sustituyen por un botón "Locked" deshabilitado.
Informes de versión
Se pueden descargar informes de versión que incluyen una lista de todas las páginas con la siguiente información:
Título
Creador
Quien actualizó
Fecha de creación
Fecha de actualización
Está en estado de borrador
Está publicada
Para descargar un informe de versión:
Abre Manage Versions.
Selecciona la versión.
En la tarjeta Lifecycle, haz clic en Download junto a Pages report.