GitBook and editing of controlled documentation

Controlled, versioned, documentation in the GovStack project is stored in GitHub using the Markdown document format. To ensure that editing of content is accessible to the widest group of people, we use GitBook to provide a user interface for people to edit content and provide the published content. The content can be edited using the GitBook UI or via Pull Requests to the GitHub repositories directly. In either case, the GitBook or GitHub change must always reference a related Jira issue that describes the motivation for change.

The following pages will describe how we use the tooling and how we create consistent documents through standards for each type of content.

The main takeaways for everyone:

1. All changes to the documentation built in GitBook will start as a Jira issue

2. Describe the reason for change in the Jira issue (this will allow us at some point in the future to know why we said the things we did)

3. The Jira issue number must appear in the Change Request title (this will then automatically be used in the Git commit message

4. If the email address you register with GitBook is the same as your GitHub email address, we will credit you with the commit!

To obtain access to the GitBook editing application:

1. Ensure you are already able to create/update issues in Jira

2. Watch the video(s) in the following pages here in Confluence

3. Post a request for a GitBook user account in the #technical-committee Slack channel