GitBook é uma plataforma que permite construir sites de documentação ou wikis da empresa. Você pode usá-lo para documentar todos os tipos de coisas, de código a APIs e como usar um produto de software.

O GitBook usa um processo semelhante aos repositórios do GitHub. A cópia principal da documentação funciona como uma cópia "mestre". Você pode então criar "rascunhos", que são semelhantes a "ramos".

Esse processo permite que muitos usuários trabalhem em um único site de documentação enquanto tratam ou evitam conflitos. Ele também permite que as alterações de diferentes ramificações passem por um processo de revisão antes de você mesclá-las.

Como começar a usar o GitBook

Você pode escolher entre vários Preços do GitBook planos. O preço dependerá se você estiver usando o GitBook para projetos de código aberto, uso pessoal ou colaboração de equipe privada. O GitBook é gratuito para uso se você o estiver usando para projetos de código aberto.

Suporte ao GitBook Markdown, uma linguagem de marcação popular com muitos benefícios para escrever ou documentar na web.

instagram viewer

O GitBook também se integra com GitHub, uma plataforma para hospedar, armazenar e editar código. Você pode vincular sua conta do GitBook diretamente à sua conta do GitHub fazendo login usando suas credenciais do GitHub.

  1. Inscreva-se no GitBook. Se você tiver sua própria conta do GitHub, clique em Inscreva-se no GitHub.
  2. Depois de fazer login, o GitBook o redirecionará para um novo wiki interno. Ele também irá pré-preencher seu wiki com algum conteúdo de amostra.

Uma visão geral da interface do GitBook

O GitBook tem várias funções que permitem construir e fazer alterações em seu site de documentação.

  1. O painel superior permite criar novos rascunhos, visualizar o histórico de alterações ou visualizar quaisquer outras discussões ou anexos.
  2. A barra lateral mais à esquerda permite que você crie vários espaços. Você pode usar espaços separados para projetos diferentes para poder separar e organizar suas áreas de documentação. Você pode expandir ou fechar a barra lateral.
  3. O painel esquerdo funciona como um menu para o site de documentação. Você pode visualizar as páginas em seu site de documentação e usá-las para criar grupos e páginas aninhadas. Você também pode navegar pelo site usando os links fornecidos.
  4. O painel inferior inclui botões vitais para o processo de controle de versão. Você pode adicionar um nome ao seu rascunho, mesclar uma alteração ou enviar a alteração para revisão.

Como criar um novo rascunho

Você pode criar um novo rascunho criando uma nova solicitação de alteração e fazendo alterações nela.

  1. No painel superior, clique em Pedidos de mudança.
  2. No novo painel que aparece no lado direito, clique no botão Rascunho aba. Isso mostrará todos os seus rascunhos ativos.
  3. A partir daqui, você pode clicar em um rascunho existente para abri-lo. Para criar um novo rascunho, clique em Nova solicitação de alteraçãoe aguarde a página terminar de carregar.
  4. No painel inferior, clique em Digite um assunto. Isso abrirá uma janela onde você pode dar um nome ao novo rascunho. Por exemplo, Nova página - Como configurar a base de código.

Como criar páginas e grupos

Depois de ter um rascunho, você pode começar a fazer alterações na documentação. O GitBook armazena suas alterações dentro do rascunho, para que elas não afetem a cópia mestre. Você pode usar a barra lateral esquerda para adicionar páginas e grupos de páginas.

  1. Crie uma nova página clicando no botão Nova página link na parte inferior da barra lateral e selecionando Nova página do documento da lista suspensa. Como alternativa, você pode passar o mouse abaixo de uma página existente e clicar no botão azul mais botão.
  2. Para criar um novo Grupo de Páginas, clique em Nova página, e selecione o Novo grupo opção do menu suspenso.
  3. Você pode renomear a página clicando nos três pontos ao lado da página ou grupo e selecionando Renomear.
  4. Comece a adicionar conteúdo para preencher sua nova página. Você pode adicionar conteúdo simples, como texto ou títulos. O GitBook também permite adicionar outros blocos de conteúdo, como imagens, anexos de arquivos, tabelas, guias ou trechos de código. Há também a opção de adicionar outras integrações, como incorporações do YouTube ou conteúdo do Google Docs.
  5. Clique no Visualização de diferenças botão no painel inferior para ver as diferenças entre o rascunho e a cópia da documentação mestre original.
  6. Depois de terminar de escrever seu conteúdo, você pode clicar em Mesclar, Enviar e mesclar, ou Enviar para revisão.

Você pode acessar o link de compartilhamento no painel superior do GitBook. Você precisará estar fora de um rascunho e visualizar a cópia da documentação principal para poder visualizar o link.

  1. Por padrão, a visibilidade do seu site de documentação é "não listada". Isso significa que você pode acessar o site de documentação usando um link privado e não por meio de mecanismos de pesquisa. No painel superior, clique no botão Não-listado botão.
  2. Selecione as configurações de visibilidade desejadas no menu suspenso. Observe que o GitBook pode bloquear determinadas configurações de visibilidade e pode ser necessário atualizar para acessá-las.
  3. Abaixo da lista de configurações de visibilidade, há um link que você pode compartilhar com outros usuários que usarão seu site de documentação. Copie este link para compartilhá-lo com outras pessoas.
  4. Abaixo do link, clique em Configurações de link e domínio. É aqui que você pode vincular um nome de domínio personalizado ou modificar parte da URL. Se você estiver usando um domínio personalizado, poderá visualizar Documentação do Gitbook sobre como configurar corretamente seu DNS.

Criando documentação usando o GitBook

O GitBook permite que você crie e trabalhe de forma colaborativa em sites de documentação ou wikis da empresa. O GitBook empresta conceitos do GitHub como ramificações e mesclagem para controlar uma cópia mestre e gerenciar quaisquer conflitos.

Você pode criar um novo rascunho para adicionar suas próprias alterações individuais à documentação. Dentro do rascunho, você pode fazer alterações no conteúdo, bem como adicionar novas páginas ou grupos de páginas. Depois de terminar de fazer as alterações, você pode mesclá-las ou enviá-las para revisão.

Se você estiver criando documentação interna para seu código Java, talvez queira explorar o Javadoc. Javadoc permite documentar seu código Java automaticamente.