ºù«Ӱҵ

Why a handbook?

Everything we do at Beautiful Canoe is formed by , and the way we share information with one another, is crucial to how those values work out in practice.

An open, publicly available handbook hits our values of *openness* and *collaboration* in an obvious way, and provides a single source of truth for developer practices at the company.But there are two other values that prompted us to create a handbook: *craft* and *edge*. Creating excellent software products means cultivating a company culture that values quality and continuous improvement. It isn't easy to get this right in a student enterprise, not least because working with the cycle of the academic year inevitably means having a high turnover of development staff.

A successful student enterprise will want to see its staff graduate and move into full-time employment, so company culture can never be fixed for long, and passing on the value of craft is essential to creating value for clients.

*Edge* for us is about a sense of moving out of a comfort zone and being continually challenged to improve every aspect of our work.The developer handbook is huge help with this: for every new developer it's a starting point for how they should communicate with one another and implement their software, but, like our processes, the book itself is never in a fixed state for long. Any of our staff can contribute to the handbook by raising a support ticket or contributing a change, and every improvement keeps us on the edge of our peak performance.

Why not a wiki?

Wikis are an obvious framework for documentation in a student enterprise. They appear to be decentralised, and to encourage autonomy, and they don't occur much of a maintenance cost.However, there are two drawbacks to wikis that drove us to move away from them.

Firstly, wikis do not encourage good engineering practices. Because wikis do not have merge- or pull-requests, they do not have a simple workflow for peer review, which leads to inconsistency and fragmentation. Although most wikis have a version-controlled back-end, the history is not easily searchable and we found that commit messages are rarely used well, where they were used at all.

Secondly, per-project wikis invite duplication, and this was one of the main reasons we moved to a single handbook - good practices from one project can easily be shared around the whole company.

This edition of GitLab Unfiltered has a fascinating discussion of why wikis may not be a good solution for developer guides in larger companies, including a number of issues around team culture:

How to create your own handbook

If we've convinced you that a handbook is a good fit for your student enterprise, then creating your own handbook needn't be difficult. There are two straightforward options:

Option 1: clone  which is built on the  static site generator. The Suddenly Remote Handbook is a template for companies to create their own handbook, based on the extremely comprehensive .

Option 2: clone our  which is built on the  static site generator and hosted on . This is our own developer handbook, so please do use it and adapt it to your own needs, but we'd be grateful if you could re-brand it and credit us somewhere!