Skip to content

Contribute to this handbook#

How to edit a page in the handbook#

  1. To edit a page, please make sure you have access to the relevant GitLab project: https://git.amazeeio.cloud/team/handbook.
  2. Then, back at the handbook.amazee.io website, navigate to the page you would like to edit.

  3. Can scroll right down to the bottom of the page and click the blue 'Edit this page' link in the footer, right above the blue footer navigation

    edit-this-page-bottom

  4. This will open the file in GitLab in the editor view. It will look something like this

    edit-file-gitlab

  5. You can make your changes directly to the file in there. Once you are happy with your changes, you can scroll down to type your commit message.

    edit-file-gitlab-commit

    This is optional - it will have a default populated commit message if you want to move quickly. However, we encourage all editors to jot down a quick commit message when possible. Commit messages will be saved to the page logs like a version history and other handbook users will be able to see what was updated on the page more easily.

These are some commit message examples

  • Fixed typos (amazee.io was capitalized)
  • Added a new section on language and tone
  • Cleaned up some formatting issues above the footer

Do not change the Target Branch.

Click "Commit changes"

Language and Vocabulary#

Please follow the following guidelines for your writing:

  • The language of the Handbook is American English.
  • Please use gender-neutral English whenever possible. Refer to people as "they" and "them" instead of "he," "she," "him" or "her."
  • Write short sentences.
  • Introduce enumerated lists (like this one) with a little bit of context (as in the previous paragraph).
  • Beware of common grammar mistakes in written English.
  • Use a spell checker before committing your changes.

We have an Style Manual that you can reference, along with our Voice and Tone guidelines (internal). You can also consult our Markdown Cheatsheet for more information on formatting.

Common Concerns#

Question

Which handbook audiences is this content intended for?

Answer

  • Current employees,
  • prospective employees,
  • or the general public which includes prospective and current amazee.io clients?

This will help understand the nature of the content and where it might belong in the handbook.

Does the content being shared need to be private from one of these audiences? If yes, then it should not go in the handbook.

Does the content being shared need to be private from one or more workstream? If yes, then it should not go in the handbook.

Is this content specific to a workstream's internal operations or would it benefit more than one workstream to know about it? If it would benefit several workstreams, consider sharing it in the handbook.

Read more about Private vs Public Handbook content

Question

How can I tell if content belongs in the handbook?

Answer

Use the handbook if the content is relevant to multiple audiences (e.g., employees, applicants, or clients) and aligns with the goals of transparency and general company information. Store content elsewhere if it’s team-specific, operationally sensitive, or doesn’t add value to a broad audience.

Example: A detailed HR policy about parental leave, including internal processes for applying, approval workflows, and legal compliance requirements.

Guidance

Public Section: Include high-level information relevant to all employees and prospective employees: "amazee.io Parental Leave Policy: Employees are entitled to [X weeks] of paid parental leave. Eligibility: Employees must have completed [X months] of service. For more information on how to apply, see the internal policy linked below."

Private Section: Internal processes, such as how managers approve leave or what forms employees need to complete, should remain in a secure, access-controlled location like Confluence or Google Drive: "For step-by-step instructions on how to apply for parental leave, including required forms and approval workflows, refer to [\this internal guid](secure link)."

Read more about Private vs Public Handbook content

Question

I'm worried this is simply too much information to share publicly - people won't read it and it'll add clutter to the handbook.

Answer

Oversharing is a valid concern, but the default rule is "open by default unless there’s a clear risk." Use the flowchart and questions provided to guide your decision. Users are encouraged not to worry about the risk of sharing too much information - the handbook content can be structured to keep it readable for all audiences, and it is not necessary for all content to be relevant for all audiences, simply that each audience can find the content they need through clear navigation. In some cases, there can be an overview page linking to a more detailed nested page.

Example: A page about vacation policies includes detailed internal procedures for logging PTO in time-tracking tools.

Guidance: Publicly share an overview of vacation entitlements and a link to the internal policy for employees: Employees are entitled to [X days] of paid vacation per year. For internal instructions on how to log PTO, refer to [this internal guide](secure link). This keeps the public handbook concise while providing useful information.

Question

How should I format content for the handbook?

Answer

Follow established templates and formatting guidelines (e.g., headings, bullets, or callouts). Ensure your content is concise, scannable, and user-focused. Link to related resources rather than duplicating content.

Question

What if the content is incomplete?

Answer

Publish the content only if it adds value in its current form. If it's critical but incomplete, add a placeholder note stating it’s a work in progress, with a timeline for completion. Example: "This section will be updated by [date]."

Question

How do I report an error or concern in the Handbook?

Answer

If you spot an error in the Handbook, whether it's a typo or a larger piece of content that's out of date, message Kelly Knight on Slack in the #team-public-handbook channel to report the issue. Where possible, please include specific details such as the page name, the type of issue, a screenshot of the problem you've identified, and, if you already know how you would like the issue resolved, the suggested resolution.

Question

How can I contribute to the handbook?

Answer

Contributions are encouraged from everyone at amazee.io handbook directly through GitLab. In the meantime, however, we are in the process of researching a user-friendly editor interface to make it easier for more users to contribute.

Flowchart for decision-making#

Use this flowchart to decide if content belongs in the handbook:

flowchart-is-this-handbook-content