GitBook es una plataforma que le permite crear sitios de documentación o wikis de empresas. Puede usarlo para documentar todo tipo de cosas, desde código hasta API y cómo usar un producto de software.
GitBook usa un proceso similar a los repositorios de GitHub. La copia principal de la documentación actúa como una copia "maestra". A continuación, puede crear "borradores", que son similares a las "sucursales".
Este proceso permite que muchos usuarios trabajen en un solo sitio de documentación mientras manejan o previenen conflictos. También permite que los cambios de diferentes ramas pasen por un proceso de revisión antes de fusionarlos.
Cómo comenzar a usar GitBook
Puedes elegir entre varios Precios de GitBook planes El precio dependerá de si está utilizando GitBook para proyectos de código abierto, uso personal o colaboración de equipo privado. GitBook es de uso gratuito si lo está utilizando para proyectos de código abierto.
Compatibilidad con GitBook Markdown, un lenguaje de marcado popular con muchos beneficios para escribir o documentar en la web.
GitBook también se integra con GitHub, una plataforma para hospedar, almacenar y editar código. Puede vincular su cuenta de GitBook directamente a su cuenta de GitHub iniciando sesión con sus credenciales de GitHub.
- Regístrese en GitBook. Si tiene su propia cuenta de GitHub, puede hacer clic en Regístrese con GitHub.
- Una vez que haya iniciado sesión, GitBook lo redirigirá a una nueva wiki interna. También completará previamente su wiki con contenido de muestra.
Una descripción general de la interfaz de GitBook
GitBook tiene varias funciones que le permiten crear y realizar cambios en su sitio de documentación.
- El panel superior le permite crear nuevos borradores, ver el historial de cambios o ver otras discusiones o archivos adjuntos.
- La barra lateral más a la izquierda le permite crear múltiples espacios. Puede usar espacios separados para diferentes proyectos para que pueda separar y organizar sus áreas de documentación. Puede expandir o cerrar la barra lateral.
- El panel izquierdo actúa como un menú para el sitio de documentación. Puede ver las páginas dentro de su sitio de documentación y usarlas para crear grupos y páginas anidadas. También puede navegar por el sitio utilizando los enlaces proporcionados.
- El panel inferior incluye botones que son vitales para el proceso de control de versiones. Puede agregar un nombre para su borrador, fusionar un cambio o enviar el cambio para su revisión.
Cómo crear un nuevo borrador
Puede crear un nuevo borrador creando una nueva solicitud de cambio y haciendo cambios dentro de ella.
- En el panel superior, haga clic en Solicitudes de cambio.
- En el nuevo panel que aparece en el lado derecho, haga clic en el Reclutar pestaña. Esto le mostrará todos sus borradores activos.
- Desde aquí, puede hacer clic en un borrador existente para abrirlo. Para crear un nuevo borrador, haga clic en Nueva solicitud de cambioy espere a que la página termine de cargarse.
- En el panel inferior, haga clic en Ingrese un Asunto. Esto abrirá una ventana donde puedes darle un nombre al nuevo borrador. Por ejemplo, Nueva página: cómo configurar la base de código.
Cómo crear páginas y grupos
Una vez que tenga un borrador, puede comenzar a hacer cambios en la documentación. GitBook almacena sus cambios dentro del borrador, por lo que no afectan la copia maestra. Puede usar la barra lateral izquierda para agregar páginas y grupos de páginas.
- Cree una nueva página haciendo clic en el Nueva pagina enlace en la parte inferior de la barra lateral y seleccionando Nueva página de documento del menú desplegable. Alternativamente, puede pasar el cursor por debajo de una página existente y hacer clic en el azul más botón.
- Para crear un nuevo grupo de páginas, haga clic en Nueva paginay seleccione el Nuevo grupo opción del menú desplegable.
- Puede cambiar el nombre de la página haciendo clic en los tres puntos junto a la página o el grupo y seleccionando Rebautizar.
- Comience a agregar contenido para completar su nueva página. Puede agregar contenido simple como texto o encabezados. GitBook también le permite agregar otros bloques de contenido, como imágenes, archivos adjuntos, tablas, pestañas o fragmentos de código. También existe la opción de agregar otras integraciones, como incrustaciones de YouTube o contenido de Google Docs.
- Haga clic en el Vista de diferencias en el panel inferior para ver las diferencias entre su borrador y la copia de la documentación maestra original.
- Una vez que haya terminado de escribir su contenido, puede hacer clic en Unir, Enviar y fusionar, o Enviar para revisión.
Puede acceder al enlace para compartir desde el panel superior de GitBook. Deberá estar fuera de un borrador y ver la copia de la documentación maestra para poder ver el enlace.
- De forma predeterminada, la visibilidad de su sitio de documentación es "no listada". Esto significa que puede acceder al sitio de documentación mediante un enlace privado y no a través de motores de búsqueda. En el panel superior, haga clic en el No incluido en listado botón.
- Seleccione la configuración de visibilidad que desee en el menú desplegable. Tenga en cuenta que GitBook puede bloquear ciertas configuraciones de visibilidad y es posible que deba actualizar para acceder a ellas.
- Debajo de la lista de configuraciones de visibilidad, hay un enlace que puede compartir con otros usuarios que usarán su sitio de documentación. Copie este enlace para compartirlo con otros.
- Debajo del enlace, haga clic en Configuración de enlaces y dominios. Aquí es donde puede vincular un nombre de dominio personalizado o modificar parte de la URL. Si está utilizando un dominio personalizado, puede ver Documentación de Gitbook sobre cómo configurar correctamente su DNS.
Creación de documentación usando GitBook
GitBook le permite crear y trabajar en colaboración en sitios de documentación o wikis de empresas. GitBook toma prestados conceptos de GitHub como ramas y fusiones para controlar una copia maestra y gestionar cualquier conflicto.
Puede crear un nuevo borrador para agregar sus propios cambios individuales a la documentación. Dentro del borrador, puede realizar cambios en el contenido, así como agregar nuevas páginas o grupos de páginas. Una vez que haya terminado de realizar los cambios, puede fusionarlos o enviarlos para su revisión.
Si está creando documentación interna para su código Java, es posible que desee explorar Javadoc. Javadoc le permite documentar su código Java automáticamente.