This site is a structured field guide. It is not a wiki, not a traditional blog, and not a documentation site — though it borrows something from each. The website format is for easy navigation and cross-referencing, but it reads like a book — and like a book, it will demand your attention. It’s long because the problem deserves it.

It is built around three kinds of content that serve different reading modes.

The manual

The manual is for reading in order. Each page builds on the last. Start at the beginning if you want to understand the whole subject from the ground up, or navigate to a specific chapter if you already know what you need.

The manual has a recursive structure. First and overview then a deep dive for non-technical people, then a deeper dive for technical people then an optional section for advanced users.

The reference section

The reference section is for looking things up. Entries are self-contained: a comparison table, a glossary definition, a template you can copy. Dip in when you need something specific; you do not need to have read the manual first.

Key terms are referenced in the Glossary section. You can use the “backlinks” to navigate to to the pages where the terms are used.

Posts

The core of the guide in the field manual is not expected to change much. The posts are the place where I can add additional reading material as time marches on. The are completely optional and they are mostly aimed at technical people.

Versioning

Currently the guide is not versioned. I’m hoping that before it sees any kind of adoption that it will be relatively stable such that I don’t have to include backwards breaking changes because the guide will always have to assume that someone might be relying it. If I do have to make a backwards breaking change, I will version it and allow the reader to globally select a version. The source of this guide is open source and the history can be retrieved in a pinch by going through the commit history.

Where to start

If you are new here, start with the manual:

• If you want context first, begin at the beginning.
• If you have a specific problem, use the reference section.
• If you want to follow along as this develops, subscribe via RSS or check the posts.

More