GITBOOK - HOW WE WORK

Where to edit pages

• Gitbook is used as a "sandbox" and finalized pages are moved to Github and made public in the current docs.

• Outline (left menu) is structured/edited in Gitbook as we work through pages and discover the right Outline and structure.

• Individual pages can either be edited directly in Gitbook or in Github using standard PR/review/merge workflow - use whatever you like most.

• Independent of tool, to ensure swift process please (also) announce requests for page review in Slack #proj-documentation-portal

• After a page has been approved, it's copied to the live docs in Github.

Page status

• To ensure one source of truth, each edited page has a "status" in the title in "()" after the title:

  • <name>: Assigned to a person for editing - others keep hands off or coordinate

  • In Review: obvious...

  • Approved: Page is ready to be moved to Github. Don't change it here anymore.

  • Live: Page has been moved and merged to Github. A link is added at the top of the page. Future edits must happen in Github.

Gitbook Change & Review process

• Before making edits, ensure you are not already in a "branch", but in the main "branch" - Left top should show "Product Docs":

  
• Check the "Change requests" - see that others are also not editing your page (check Drafts, In Review)

• Click "Edit" (right hand side)

• Name you "Change" (PR) - e.g. below: "Add Instructions" instead of "brian.munkholm's Aug 25 changes"

  
• Make small "Changes" - one per page, unless the changes are bound together across multiple pages

• "Request a review"

• Reviewers comments:

  
• Author adjusts page based on feedback and Merge

Editing pages in Github

• It's easy to edit a page in Github. From the live docs, click "Edit Page" (top right corner):

  • Edit the markdown file (directly in Github or separately) and check rendered changes via readthedocs generated automatically by CI (it may take a few minutes):

    • Link can be found in the CI section at the bottom under "All checks passed": docs/readthedocs.org:cratedb-guide

      
  • Create a PR and send for review.

  • Include a link to the Preview in the description

• Most changes (PR's) are done in the cratedb-guide repo, and the status of PR's can be followed there.