Does your student enterprise need a developer handbook?

Over at Beautiful Canoe our developer handbook has become an essential part of how we deliver high quality products for clients. Now that, like everyone else, we are working remotely, the handbook is more important to our productivity than ever.

Why a handbook?

Everything we do at Beautiful Canoe is formed by our values, 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 GitLab's Suddenly Remote Handbook which is built on the Hugo static site generator. The Suddenly Remote Handbook is a template for companies to create their own handbook, based on the extremely comprehensive GitLab Engineering Handbook.

• Option 2: clone our docs.beautifulcanoe.com repository which is built on the mkdocs static site generator and hosted on GitLab Pages. 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!