Estructura del proyecto

Los proyectos de DeveloperHub ofrecen la máxima flexibilidad en comparación con otros servicios disponibles.

¿Cómo se estructuran los proyectos?

Los proyectos están en lo más alto de la jerarquía. Cada proyecto puede contener lo siguiente:

• Páginas de inicio.

• Una o varias versiones.

• Registros de cambios.

Cada versión puede contener:

• Secciones de documentación.

• Referencias de API.

Cada sección de documentación contiene:

• Un índice de una o varias páginas, categorías y enlaces externos.

Los distintos proyectos, aunque pertenezcan al mismo equipo, no están vinculados entre sí y sus datos están aislados. Puedes enlazar entre proyectos mediante enlaces externos. Cada proyecto puede tener sus propias personalizaciones, marca, aspecto y equipo.

Ejemplo de configuración

Un proyecto de jerarquía plana, para una documentación más sencilla, podría tener esta configuración:

• Proyecto: Pied Piper

  • Versión: latest

    • Documentación: Docs (con cualquier número de páginas)

Un proyecto más grande podría tener esta configuración:

• Proyecto: Pied Piper

  • Versión: v1.0

    • Documentación: Getting Started

    • Documentación: Android SDK

    • Documentación: iOS SDK

    • Documentación: Knowledge Base

  • Versión: v2.0 (Latest)

    • Documentación: Getting Started

    • Documentación: Android SDK

    • Documentación: iOS SDK

    • Documentación: Knowledge Base

¿Y si no necesito versiones?

Si tu documentación no tiene versiones, simplemente puedes usar un nombre genérico para la versión predeterminada, como el nombre de tu proyecto. Dentro de esa versión puedes tener toda la documentación y las referencias de API que necesites, como Guía del usuario, Base de conocimientos, preguntas frecuentes, SDK de Android, SDK de iOS, etc.

Si solo tienes una versión, que es la predeterminada, el nombre de la versión ni siquiera aparecerá en la URL según nuestra estrategia de URL.

Por ejemplo, nuestra propia documentación no tiene versiones y solo tenemos un v1.0. Sin embargo, si estás en esta página, notarás que el enlace en realidad es support-center/structuring-documentation, sin mención de v1.0.

Ejemplo de configuración

Un proyecto sin versiones podría tener esta configuración:

• Proyecto: Pied Piper

  • Versión: pied-piper

    • Documentación: Getting Started

    • Documentación: Android SDK

    • Documentación: iOS SDK

    • Documentación: Knowledge Base

Recuerda que puedes quitar el selector de versiones de la barra de navegación superior del lector mediante un ajuste; consulta Ocultar el selector de versiones.

¿Para qué sirven las versiones?

Las versiones actúan como contenedores de documentación y referencias de API que se pueden clonar.

Mejores prácticas

Para aprovechar DeveloperHub al máximo, recomendamos lo siguiente:

• Es importante usar el versionado correctamente, ya que la página de inicio muestra el contenido de la versión predeterminada/más reciente.

• Si una documentación tiene demasiadas páginas, quizá convenga separarlas en documentaciones distintas.