We have improved the documentation for factory_bot, our Ruby library that makes it easy to quickly instantiate new model objects. The new book contains a general guide, a cookbook with solutions to common problems, and a quick reference. The factory_bot wiki contains details on how to best integrate factory_bot into third-party libraries.
In this post we want to acknowledge the work that lead to this, talk about the decisions we made, and provide excitement about the future.
History
At factory_bot’s inception in 2008, README.md contained examples of how to
use it. In 2011 we moved them out into their own document,
GETTING_STARTED.md, so they could be easier to read.
This file has served us well over the years. It gave us a central place to add documentation without too much thought, and it made searching simple. However, as it has grown it has also become harder to justify. The table of contents was managed manually, much of the content assumed that you read it from top to bottom, and frankly the endless scrolling was intimidating.
After some discussion, planning, and trials of newer documentation software, we hope that we found a pattern that will serve us for the next stage of factory_bot growth.
Wiki
One way to divide the documentation is to consider: what documentation needs to
change because of changes to the factory_bot repo, and what documentation
changes are driven by external repos. For example, adding the traits_for_enum
method to factory_bot would drive a change to our documentation in the same
pull request, but if RSpec were to change their include methodology then we
won’t find out about that directly.
This tactic for dividing docs leads to the first split: wiki vs non-wiki. We chose to move all integration documentation into the GitHub wiki for factory_bot. This means that anyone with a GitHub account can pop in and modify a page without us being a bottleneck. If you are the author of a new test framework, or a user of an alternative ORM, or anyone else who knows about integrating factory_bot into a third-party library, we encourage you to stop by the wiki and spruce it up.
Getting started with a book
The GETTING_STARTED.md document had grown to be a full guide – it extended
beyond just a simple quick start. It documented all the techniques for using
factory_bot, extensively and verbosely. This kind of writing could use
something beefier.
We explored some larger scale formatting programs and decided on mdBook. It is a simple command-line runner that is easy to use from GitHub Actions; it worked with the existing Markdown with few modifications; the generated HTML has features like themes, search, table of contents; and it’s a popular, maintained tool used in other programming communities such as Rust.
As a first step we moved GETTING_STARTED.md into mdBook format, each chapter
in its own file. Then we spent two days on a cleanup pass where we
contextualized each chapter so it can make sense on its own.
This final pass serves as the guide, explaining how specific parts of factory_bot function in detail. This means that it is not terse, and it also means that it doesn’t describe how to combine multiple parts of factory_bot to solve a puzzling model.
Reference
That brings us to the reference. This is an entirely new section of the documentation that tersely describes factory_bot functionality in the level of detail needed for someone who uses factory_bot often. Facts such as method arguments, return types, and algorithms are what gets documented in the reference section.
This is the type of documentation that would often be written in YARD or RDoc,
but factory_bot is in an odd place there. Most of it is built up of private
methods and classes, and the bits that are exposed are in unpredictable
classes. As a user, you never deal with the FactoryBot::Definition class, for
example, but you do use some of its methods.
Thus, the YARD-style documentation lives in the reference section of the book, where it can be presented in a coherent and consistent manner.
Cookbook, and beyond
Once you’ve read the whole guide, you will still need to understand how to apply factory_bot to your situation. Most of the time this will be clear and straightforward, but sometimes you need to figure out how to piece together multiple techniques to solve a puzzle.
Introducing the cookbook. The factory_bot cookbook describes best
practices and techniques for working with things like ActiveRecord
associations, combining transient blocks, after hooks, sub-factories, and
create_list builders.
This is the section we are most excited to expand based on lessons learned from two decades of client work across hundreds of projects, and where we’d love to see pull requests from you where you share your knowledge.
The cookbook is where we’ll be looking to think hard about new features and extensions to factory_bot as we take it into the future. Perhaps today’s cookbook chapter could be tomorrow’s method reference.
Feedback
This is a big change so we’d love to hear from you all. Please open issues with ideas for further improvements, or common puzzles you would like to see addressed in the cookbook. We want your help building the factory_bot that serves the Ruby community!
Visit our Open Source page to learn more about our team’s contributions.
