--- title: New Docs for factory_bot teaser: 'We have improved the documentation for factory_bot, the fixture replacement. ' tags: ruby,factory_bot,open source author: Mike Burns published_on: 2023-05-24 --- We have improved [the documentation][book] for [factory\_bot][fb], 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][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][wiki]. 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][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][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][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][fb] that serves the Ruby community! [fb]: https://github.com/thoughtbot/factory_bot [book]: https://thoughtbot.github.io/factory_bot [wiki]: https://github.com/thoughtbot/factory_bot/wiki [mdBook]: https://rust-lang.github.io/mdBook/ [guide]: https://thoughtbot.github.io/factory_bot/setup/summary.html [reference]: https://thoughtbot.github.io/factory_bot/ref/build-strategies.html [cookbook]: https://thoughtbot.github.io/factory_bot/cookbook/has_many-associations.html [open issues]: https://github.com/thoughtbot/factory_bot/issues Visit our [Open Source page](https://thoughtbot.com/open-source) to learn more about our team's contributions.