Prepared by Tim Briscoe, Systems Engineer IV, and Brianna Heron, GHI Summer 2021 Student Employee
Purpose of this Document
The goal for this document is to serve as a guide for getting started as well as updating/creating new materials in GitBook. Think of this guide as initial training for the GitBook software, best practices, and pro tips rather than a step-by-step guide for a start-to-finish project.
Training Materials
Web-based documentation is essentially a collection of formatted text and images. Gitbook allows users to create end-user documentation through an easy-to-use editing interface. Behind the scenes, Gitbook is a collection of text files formatted using Markdown (more on that later). These files can be synced with GitHub for version control and alternate distribution. Each Gitbook project has a corresponding site for end-users.
When it comes to formatting, you can do in-line styles like bold, italic, and strike-through. You can also do standard block or paragraph-level formatting like heading levels 1 through 3, bullet/ordered lists, quotes, tables, etc. There are also special, Gitbook-specific formatting blocks called “Hints.” Essentially these are attention-grabbing paragraphs with an alert icon.
The best way to learn how to use Gitbook is by simply trying it out. You can use the following link to create an account. Once you’re in, you’ll see the documentation projects that Gitbook calls Spaces. One of the spaces is called Testing Area where you can play with all the available features/formatting. It is a private area for our use only.
https://app.gitbook.com/invite/openhie?invite=-MYyeRf5i4HfflLYAkg-
Other resources that may help you best understand how to use Gitbook:
- Gitbook documentation
- Hands-on video of Gitbook from another user
- A quick hands-on video
- Another quick video on organizing sections and linking between them
Markdown primer
Markdown formatting is the heart of Gitbook. When you write/edit text, you’re actually creating Markdown formatting behind the scenes. Gitbook abstracts that way for a WYSIWYG experience. That’s a good thing because Markdown can become tedious. It’s not necessary to know Markdown for using Gitbook but it may be helpful. This is a nice introduction.
https://www.markdownguide.org/getting-started/
Pro-Tips
Roles:
Admins and Owners:
- Edit and manage content in spaces and organization
- Invite and add members
- Create teams, remove team members, give team permissions
- Access to drafts and unpublished changes
- Only owners can delete an organization
Writers:
- Edit and manage content in a space but not an organization
- Access drafts and unpublished changes
- Comment on drafts or content
- Have access to edits, activities, analytics in spaces
Readers:
- Can only access and read all published content created in spaces
- Can’t edit, comment, or manage any content
**User roles can be changed at any time**
- If you accidentally merge content before it is ready, you can revert those changes by clicking on Restore
- There are two palettes – insert and command
- Command Palette- helps with structuring your document. Includes features such as paragraph, headings, lists- bullet, number, task list, hints or callouts, code blocks, quote, image block, tables, page link, repositories, tabs, files, etc. Essentially, this palette helps present your information better and in different ways to make it more appealing for readers
- Insert Palette- helps with making content more visually appealing. Includes math formulas, emojis, and inline images which are:
- Inline size- sized to the font
- Original size- it is still inline, but it is the original size of the photo
- Convert to block- turns the inline image to a block image with its original sizing
- Groupings are important if you want to house data that is similar. Underneath the groups you can create pages and indent pages to make those housed underneath each other
- When updating something you must save and then merge. If you don’t merge the content, then your work might not be shown on the next draft
- You can leave comments by hitting the + button the right side of the screen, but make sure to save them. They will appear on the edits tab on the left of the screen
- If you are wanting to export files with Google Docs:
