Before ROM 1.0.0 can be released the docs on the website should be improved. It’s a major effort though, we started a discussion to gather ideas what should be improved, and how.
If you’re interested in helping with 1.0.0 release, working on the documentation is now one of the most crucial tasks. Please get in touch if you’d like to contribute new guides, tutorials or work on improving the existing ones.
Cheers <3
Hey, I would like to contribute to this very much. I’m starting to use it now, so I need to learn a lot of ROM before I start documenting. But I think that in a week or two I’ll be ready for it.
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 
I 100% agree that there needs to be a single Recommended Way, and would like to add that the Recommended Way should involve as few steps and concepts as possible before getting running. That’s the primary reason that the docs rewrite have focussed on the DSL - it hides classes and ideas that are unimportant for getting something to read and write.
As for dry-data, I’m personally leery of including any library for model objects, preferring to reduce the up-front moving parts. Adding it in more complex guides makes more sense to me. If there must be a model library used at all times, it’s fair enough that dry-data is a front-running contender. That said, if there was a gem to just include Immutable, that would sit better with me.
One thing that needs to be decided is which hills to die on. @solnic and others are insistent that everything be immutable all the time (I’m indifferent) and dry-data also seems to assert that types are a good way to go (I lean to disagreeing based on my personal experience, but I’m only one data point). Neither of these battles are really core to ROM - you can use ROM type-free and mutably.
Getting folk onboarded to a behaviour change is easier when the change is small from what they’re used to, instead of upending every single thing all at once. Once they’re using ROM, it’s easier to “upsell” other ideas, since the cost of any change is lower in ROM than in AR (hooray for clean boundaries!)
As for how to do things with a particular adapter, a possible layout could be:
Where 2 is essentially the outside API of Repository/Relation/Commands, and then 3 is their implementation.
Update: The new documentation has started to get transferred from the temporary Google doc into the more permanent home of this rom-rb.org fork. Further 1.0 docs expansion will continue on that fork, with occasional pull requests as segments become complete.
A deployment of the fork is hosted at rom.tenjin.ca.
Feedback can be given either in the rom gitter channel (if it’s short), or through github issues on the fork.