That's great, thank you. We're going to create a branch with new docs under rom-rb.org repo in the first weeks of January. ROM 1.0.0 will be released before new docs arrive though. I realized that the current pre-release will be blocking other gems as they are in a pre-release state too and it complicates further development and release process. With ROM 1.0.0 released we're going to be able to focus on adapters and other extensions, esp repository, and provide nice higher-level documentation, thus it's important to push ROM 1.0.0 final ASAP.
I should mention that after taking a break from working on ROM recently (I focused a lot on dryrb gems for the past few weeks) I feel like I have a better perspective. Previously I was so deep into ROM core APIs, trying to explain it through docs and guides but now I clearly see it was not a good strategy in the long term. Most people need to understand how to use ROM with specific databases, and that's what we should focus on when working on the docs. The exception is the setup API and explaining that ROM ships with a container that provides access to registered components. But that's the only common API that should be documented separately. Everything else should focus on adapter-specific docs, even if it means some level of duplication.
Another thing is docs for repository and how to use it with various "model" backends. Personally I would vote for choosing dry-data as the recommended library. I've found it to be the best fit, with its type-safe structs and immutable value objects. It's very fast and flexible too and I'm sure I can make it even better. There's still a lot to be done to improve its error handling though, but I will do it sooner or later.
The blessing and the curse of ROM is its flexibility, if we don't decide on a recommended, one way of using ROM, people will be continuously confused about it. Most Rubyist come from Rails, and their knowledge about designing systems is based on their experience with ActiveRecord, and that very pattern is a simplification of the design process and probably the reason why so many people easily pick it up. You don't have a choice wrt how your domain objects will look like because your databases dictates that. With ROM you can and actually should think about custom data types that you will construct from the data that you fetch from the database and it's a whole new level of experience for many people.
I'm also not sure what to do with rom-mapper docs, I know many people find it very useful but personally I'm not happy with its DSL and I don't think it's a good solution in the long term. I'd much rather focus on transproc to be honest. This needs a lot of discussions before we make any decisions though