DZone

<div content="" data-mobiledoc="{"version":"0.3.2","atoms":[],"cards":[["image",{"src":"https://arctype.com/blog/content/images/2021/04/Arctype-1-1.png","width":1833,"height":808,"caption":"Arctype documentation powered by GitBook","alt":"Arctype documentation powered by GitBook"}],["html",{"html":"

n

The fast and easy-to-usenSQL client for developers and teams

n n tntn

"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Gitbook-2-3.png","width":1832,"height":794,"caption":"Initial screen after signing up for GitBook","alt":"Initial screen after signing up for GitBook"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/new-space-3.png","width":1887,"height":866,"caption":"Starting page for a new space/project Gitbook","alt":"Starting page for a new space/project Gitbook"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Create-a-New-Repository.png","width":1890,"height":1165,"caption":"I created a new private repository named GitBook-Tutorial","alt":"I created a new private repository named GitBook-Tutorial"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1066-.png","width":1888,"height":797,"alt":"screenshot of repository quick-setup on GitHub for GitBook"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Github-integration.png","width":1891,"height":801,"caption":"Link your GitHub repository","alt":"Link your GitHub repository"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1068-.png","width":1884,"height":803,"caption":"Select the branch you want to link with GitBook","alt":"Select the branch you want to link with GitBook"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1070-.png","width":1884,"height":797,"caption":"First synchronization content","alt":"First synchronization content"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1071-.png","width":1195,"height":502,"caption":"Successful GitHub integration","alt":"Successful GitHub integration"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1076-.png","width":1891,"height":796,"caption":"Adding new content to your space","alt":"Adding new content to your space"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1078-.png","width":1861,"height":799,"caption":"Changes are successfully pushed to GitHub","alt":"Changes are successfully pushed to GitHub"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1082-.png","width":1891,"height":801,"caption":"Sharing your work","alt":"Sharing your work"}],["image",{"src":"https://arctype.com/blog/content/images/2021/04/Screenshot–1081-.png","width":1920,"height":950,"alt":"GitBook new page preview"}]],"markups":[["strong"],["a",["href","www.outreachy.org"]],["a",["href","http://www.intermine.org"]],["a",["href","https://gitbook.com"]],["a",["href","https://arctype.com/"]],["a",["href","https://readthedocs.org/"]],["a",["href","https://mkdocs.org"]],["a",["href","https://docsify.js.org/"]],["em"],["a",["href","https://en.wikipedia.org/wiki/WYSIWYG#:~:text=In%20computing%2C%20WYSIWYG%20(%2F%CB%88,document%2C%20web%20page%2C%20or%20slide"]],["a",["href","https://github.com/new"]]],"sections":[[1,"p",[[0,[],0,"For the past three months, I have had the distinct pleasure of working as an "],[0,[0,1],2,"Outreachy"],[0,[],0," intern for an open-source project called "],[0,[0,2],2,"Intermine"],[0,[],0,", where I was tasked with creating new user training documentation. For this project, I entirely rewrote the Intermine user documentation—which included images, code snippets, tables, mathematical formulas, and more—using GitBook. This guide will share my experience creating technical documentation using GitBook and act as a de-facto quick-start guide to GitBook."]]],[1,"h2",[[0,[],0,"What is GitBook?"]]],[1,"p",[[0,[0,3],2,"GitBook "],[0,[],0,"is a collaborative documentation tool that allows anyone to document anything—such as products and APIs—and share knowledge through a user-friendly online platform. According to GitBook, “GitBook is a flexible platform for all kinds of content and collaboration.” It provides a single unified workspace for different users to create, manage and share content without using multiple tools. For example:"]]],[3,"ul",[[[0,[],0,"Individuals can use GitBook to track their personal projects, add notes or ideas."]],[[0,[],0,"Teams can centralize and share their internal knowledge bases on GitBook, which improves collaboration and makes finding information more convenient."]],[[0,[],0,"Organizations, including "],[0,[4,0],2,"Arctype"],[0,[],0,", can create beautiful docs to guide and support their users and contributors. "]]]],[10,0],[10,1],[1,"h2",[[0,[],0,"Why GitBook?"]]],[1,"p",[[0,[],0,"Given that digital documentation solutions have been around since the dawn of the digital age, it is entirely fair to ask, “why does the world need another documentation tool?”—or in other words, “why should anyone use GitBook?” Of course, other good solutions can be utilized to build user and developer documentation, such as "],[0,[5,0],2,"ReadTheDocs"],[0,[],0,","],[0,[6],0," "],[0,[0],2,"MKDocs"],[0,[],0,", and"],[0,[7],1," "],[0,[0,7],2,"Docsify"],[0,[],0,". These popular tools share some features with GitBook, including supporting custom domains, PDF export, search, and navigation abilities. However, GitBook outperforms these documentation solutions in many aspects, including but not limited to:"]]],[3,"ul",[[[0,[],0,"Superior customization capabilities to reflect any brand’s identity"]],[[0,[],0,"Great plugin system with almost 700 plugins that extend the default GitBook functionally"]],[[0,[],0,"The most convenient GitHub integration you’ll find to easily sync your documentation with GitHub and keep everything up-to-date!"]]]],[1,"p",[[0,[],0,"Therefore, in a scenario where requirements like advanced branding, customizable UI design, and features extensibility are essential, existing alternatives cannot compete with GitBook. "]]],[1,"p",[[0,[],0,"As a more concrete example, Intermine had some specific requirements for my documentation overhaul project, which included search and customization abilities, as well as markdown support. Similar to the scenario described above, I started comparing several options and ultimately chose Gitbook to create the new user training material because it:"]]],[3,"ul",[[[0,[],0,"Comes standard with both a great online "],[0,[8,9],2,"WYSIWYG"],[0,[],0," editor and markdown support"]],[[0,[],0,"Allows for team collaboration"]],[[0,[],0,"Can be customized to match any organization’s branding"]],[[0,[],0,"Offers a base version that is entirely free for personal use, and the paid, premium version can also be licensed to open-source projects free of charge"]],[[0,[],0,"Can display your content, publicly or privately, with anyone—including non-GitBook users."]],[[0,[],0,"It can be configured to synchronize your content with GitHub and also create PDF versions of your documentation."]],[[0,[],0,"It supports integration with other tools, such as Slack, Intercom, and Google Analytics."]]]],[1,"p",[[0,[8],1,"Disclaimer: The above list is not comprehensive nor complete."]]],[1,"h2",[[0,[],0,"GitBook Basics"]]],[1,"p",[[0,[],0,"According to the GitBook documentation, there are some fundamentals that you’ll need to know to start with GitBook. I will demonstrate these basics using the Arctype documentation written in GitBook. "]]],[3,"ol",[[[0,[0],1,"Space: "],[0,[],0,"in GitBook, spaces are projects – public or private – where you can start writing your personal notes, documenting a product, or sharing knowledge-base simultaneously with your team or individually. "]],[[0,[0],1,"Organization: "],[0,[],0,"an organization is a place where one or several projects are stored. If your organization works on many different projects, you can create a space for each one, and you can invite members to join your organization and start collaborating! "]],[[0,[0],1,"GitHub Integration: "],[0,[],0,"you can easily synchronize your work on GitBook with any GitHub repository, which keeps your documentation up-to-date."]]]],[1,"h2",[[0,[],0,"Step by Step Guide to Creating Your First GitBook Documentation"]]],[3,"ul",[[[0,[],0,"First, you need to sign up for GitBook using your email, GitHub, or Gmail account. As you can see in the screenshot below, you will first be prompted to create a new space dedicated to your projects that you can share publicly or with your team. You can also create an organization that might include several projects or spaces. "]],[[0,[],0,"I will keep things simple, and you’ll only need to create a new space to follow along. I created a public space, GitBook Tutorial, shown in the following screenshots. The initial page of your new space should look something like this: "]],[[0,[],0,"As previously mentioned, you can integrate your GitBook content with a Github repository. So, you will have to "],[0,[10,0],2,"create a repository"],[0,[],0," in Github – public or private – to link with your new Gitbook space or use a pre-existing one. I’ve created a new private repository for the sake of this guide. "]]]],[10,2],[10,3],[10,4],[1,"p",[[0,[],0,"Remember to not edit the new repository on GitHub for now. "]]],[10,5],[3,"ul",[[[0,[],0,"To set up the GitHub integration, click on the Integrations tab from the left sidebar and then select the GitHub checkbox, which will allow GitBook to access your GitHub account. Now, you must choose the repository that you want to link. Since my repository is private, I clicked the "],[0,[0],1,"List all repositories"],[0,[],0," option and chose the newly created repo. Note, if your repository is public, select "],[0,[0],1,"List only public repositories "],[0,[],0,"instead. "]]]],[10,6],[1,"p",[[0,[],0,"During the setup, you will be asked to select branches to synchronize. GitBook imports the master branch by default; however, you can specify other branches. "]]],[10,7],[1,"p",[[0,[],0,"Next, you will be promoted to choose the content to be used for first synchronization. Since our new GitHub repository is empty, we” for=””>

For the past three months, I have had the distinct pleasure of working as an intern for an open-source project called Intermine, where I was tasked with creating new user training documentation. For this project, I entirely rewrote the Intermine user documentation — which included images, code snippets, tables, mathematical formulas, and more — using GitBook. This guide will share my experience creating technical documentation using GitBook and act as a de-facto quick-start guide to GitBook.

What is GitBook?

GitBook is a collaborative documentation tool that allows anyone to document anything—such as products and APIs—and share knowledge through a user-friendly online platform. According to GitBook, “GitBook is a flexible platform for all kinds of content and collaboration.” It provides a single unified workspace for different users to create, manage and share content without using multiple tools. For example:

Source: DZone