Skip to content

What's New in the Handbook?#

The handbook has undergone a significant revamp in the last two months. These are the major changes.

Current status#

The updated public handbook can currently be viewed at: https://nginx.dev.amazeeio-handbook.ch4.amazee.io/.

It is not yet live. When it is made live, the updated handbook will be viewable at handbook.amazee.io.

The handbook documentation files are stored in the GitLab project at https://git.amazeeio.cloud/team/handbook/ and the site uses MkDocs, an open-source static site generator. We are using the Material theme.

There are a few pages which have been flagged as missing content or with potentially incorrect content, though there are far more content issues remaining beyond those that are still being worked through. These will be presented to stakeholders for review and clarification, following which the relevant pages will be updated. These are mainly operational points and questions. In general, there is still a lot of content duplication and formatting issues throughout, which are being resolved in waves with stakeholders because of the sheer volume of content.

Content migraton and consolidation#

The content from the Internal Handbook Confluence space has been merged with the content in the public handbook, originally at handbook.amazee.io.

This involved stakeholder engagement and collaboration on new policy documentation, such as the Private vs. Public Handbook Policy, and a significant restructuring of the site navigation in order to make the reading journey intuitive for the different handbook audiences.

Content writing and rewriting#

Some outdated content originally located at handbook.amazee.io has been rewritten to be more accurate and up-to-date alongside the fresh content from the Internal Handbook in Confluence.

Additionally, with the creation of many new pages, new content has been created to provide overviews on various topics such as employee regulations and policies, resources, and to serve as landing pages for different audiences.

A snapshot of new pages that have been created that did not previously exist in the public or internal handbooks:

Mkdocs site formatting#

The site itself has undergone significant aesthetic changes over the last few weeks. This includes:

  • The addition of dark mode
  • The addition of navigation tabs at the top of the site
  • New landing pages for each audience (prospective candidates, new employees, employees, and the general public)
  • In-depth restructuring of the vertical navigation within each section, including parent/child pages
  • Reformatting of all pages to present a cohesive look-and-feel
  • The addition of footer content to show when last each page was updated, along with a link to 'edit this page' that opens the page in the GitLab project in the editable view
  • The use of admonitions (information boxes) throughout to bring the content to life and match the formatting and structure of the Confluence content as closely as possible
  • Mobile testing of all new additions and changes to make sure this looks great on mobile too

Still to come#

  • Personalisation: I'll be reaching out to stakeholders for some images and information to personalise the pages under the About section a bit more. E.g. team photos, conference photos, quotes etc.
  • Making editing easier: We're in the research phase to find a suitable WYSIWYG editor for this handbook. There are 14 tools under consideraton, not including extensions and third-party plugins. The research phase involves free trials, sales calls, reading docs, testing extensions, and replicating handbook content in the tool to test navigation structures and page formatting.
  • Training: Once the research phase is wrapped up for a new editor, we'll conduct training on the new tool and how to edit the handbook. Unfortunately, there is a gap between "making editing easier" and this step while we find a new tool, but we hope to keep it super short so that there won't be two rounds of training required: training in Markdown and GitLab in addition to training in the new tool. We're aiming for a gap of no longer than one month, during which we encourage editors to reach out to Kelly Knight in the #team-public-handbook Slack channel for any and all support.
  • Changelog: I'm working on developing a changelog consisting of all recent commit messages made to this project in GitLab and adding it to this page. This will serve as a digest of handbook changes.