Please consider bringing back the old readme-style documentation

[arowla]

Please consider bringing back the old GETTING_STARTED readme-style doc. It was far easier to navigate and find examples and needed info. The new docs are split up so granularly that it's really hard to find what one is looking for, even for a longtime user of the gem. It used to be so easy and fun to scroll the doc and browse the examples for usage ideas. Sometimes I didn't even know which feature I needed, but by scrolling the examples, I could recognize something that would be helpful. Clicking through every page of the book is cumbersome and doesn't even come close to the old experience.

The old doc was one of the best in the business. Truly a joy to read and use. Please consider bringing it back.

[sarahraqueld]

Thanks for your feedback. We'll take that into consideration. I'm keen to hear opinions from others as well.

[filipewl]

I'd like to vouch for this as well. I've been a long time FactoryBot user that have been away for a few years and just now I needed to take a look at the documentation and the new cookbook felt visually limiting. I think @arowla was able to perfectly convey what I felt.

I found out https://github.com/thoughtbot/factory_bot/blob/9af6c6a5ba097e424663847f9478e314d464abd8/GETTING_STARTED.md is still available. Although it's marked as deprecated, I guess it's something I can use to start my exploration.

[aviemet]

Adding to this, one problem is that topics seem to have been added without any thought as to their organization. There are 16 sections of definitions with no usage examples before getting to the useful parts of the documentation. Then, beginning at section 17, there is actually useful documentation, but the usage examples are not only separated from their definitions covered in the previous 16 sections, but also broken up in such a granular way that maintaining the context of what you're learning is difficult.

For instance, in section 27.1 about traits as implicit attributes, the example provided is referencing the factory definition from the previous section, but that's not clear from looking at the page. If arrive at that page without having been to the previous one, I'm now lost and confused. I would much prefer to have one long page per feature, and the links to subsections scroll to page anchors, rather than each subsection be a separate page.

Arriving at the documentation as someone looking for a quick answer to a specific question, or a method reference list, the book is very confusing. I see that there's a section called "8. trait". Great, that's the feature I need to understand to solve my problem. Except, it only has two short and basically unhelpful sentences with no code examples, and then a link to an unrelated page about method_missing. Confusingly, traits are discussed in more detail way down in section 27, but there's no link to that page and no indication that there's more information available about traits. Taking another topic as an example, to learn about defining associations, these are the available sections:

• "6. association"
• sections 25 through 25.7 about Associations
• "36. has_many associations"
• "37. has_and_belongs_to_many associations"
• "38. Polymorphic associations"
• "39. Interconnected associations"

To make these docs more readable, there should only be a small number of top-level headings and anything remotely relevant to them should be under them as subtopics. Subtopics should all be on a single, scrolling page and TOC links to subtopics should cause scroll events to page anchors rather than render an entire view, losing context and usage examples

I appreciate the attempt to make better documentation, especially for a tool as ubiquitous as FactoryBot. It would be great if it was done well, but the current implementation is more confusing than helpful. If this is the official docs page for the project, it should be better than a long README.md file in a github repo.

Sorry for the novel, I didn't mean to write so much about this.

[pdfrod]

I'm strongly in favor of the old sytle documentation as well. Whenever I go to the new docs I either can't find what I'm looking for or I take ages to find it. I'm finding myself always going to back to the old GETTING_STARTED.md documentation.

[sriedel]

Until I stumbled across this issue, I wasn't even aware that GETTING_STARTED.md was deprecated. It's so ingrained in my lookup process, that I access it over the URL bar, and just start scrolling or searching for a keyword that I never really see the deprecation declaration.

I'd rather not see it go, it's been a constant companion for a decade and a half-ish and still works as a succint repository of what to do to this day.