I hope you’re doing well and you’re happy dry-rb users We’ve come a long way since dry-rb has been established in 2015 and I’m really proud of what we’ve achieved together. All the gems provide a lot of very powerful features; furthermore, due to the nature of dry-rb you can compose gems into more powerful abstractions.
This is all great and awesome but there’s one big caveat: for many people it’s a challenge to figure out how exactly they want to use dry-rb gems. For us, core developers and maintainers, it’s a challenge to provide educational resources in the form of user docs, api docs, tutorials, guides and so on.
I’ve been thinking about this problem and trying to solve it for a couple of years. Unfortunately the harsh reality is that I, as well other core devs, simply never have enough time to properly handle documentation and other resources. This is a huge effort, easily comparable to the effort that goes into implementation and maintenance of the code itself.
Here’s the current state of things when it comes to docs:
We have a zulip chat and this forum where people can ask questions and get support
This is good but here are some issues:
Many user docs on dry-rb.org have uncovered features
Docs should be organized better - gems should be grouped into “tiers” so that it’s easier to understand which gems are “core” and which are more high-level, and high-level guides written to show how the gems can work together
API docs should be improved and better integrated
Zulip (chats, in general) are not a good way to provide support - we’d prefer to move “support” to this forum
Given that literally years are passing and we just can’t find enough time to properly deal with all of this the time has come to openly ask for help from the community!
We need a team of documentation maintainers - if you’re interested in helping with this or have some feedback to share - please do this in this thread!
This very thread is our starting point, so please share what you think that should be done, what the priorities should be and so on. Once we have a rough list of things to do here, I can add issues on GitHub and we’ll be able to take it from there.
Here’s a rough “ground work” todo from my point of view:
Come up with a system for writing and verifying code examples
Come up with a system for listing features (using YARD and custom tags could be a cool thing to do) - this way we could measure doc coverage at a high-level, of course we should probably start with a simple solution like a list stored in a yaml file within docsite directories in each repo and just use it as a reference
After this is done, I’d say that priorities should look like this:
Improve dry-validation docs - some features are not documented and existing docs may have missing info too
Same thing but with dry-types
Revamp dry-system docs - we’ll have 1.0.0 released very soon so it’s a perfect moment
Review and figure out how to improve docs for:
dry-configurable
dry-monads
dry-struct
I’m very consciously skipping dry-schema here because 2.0.0 will change method sigs for most of the DSL methods so it makes no sense to deal with doc improvements now. I’ll be working on this very soon btw.
Overall, my suggestion is to think about what you need because if you’re working on OSS that matches your needs/interests, then it’s going to be smooth and joyful I also think that spending some time on the technical ground-work is important - ie if we had a nice system for code example verification we wouldn’t waste time on reviewing things manually, dealing with mistakes that people report (which always happen) and so on.
One article/idea I had as a start is basically “Here are the things you should know about Ruby when working with Dry”. As an example, dry leverages callable objects as a core abstraction through many of its gems, but this is not a common pattern in more popular ruby frameworks like rails. I’m sure there’s a few other themes that could be identified that would bootstrap a new adopter to common language abstractions in dry that are less commonly used elsewhere.
I’m not a huge fan of the BDD thing, but one tool I think that really shines is the relish framework rspec uses to do their documentation. I’m never at a loss to find an example of an rspec feature that I forgot how to use. Since most of the testing is in rspec, perhaps it would be a lower lift to provide executable examples.
The documentation is actually not so weak, in the small. The problem is the big picture, as I think you’re aware. What is this thing? How do I think in dry-rb?
Rails actually had the same problem for years, if you wanted to understand something you had only source code, API docs, the book DHH wrote, and the blogosphere. That often meant source code + begging for help on IRC.
What changed the situation was the Rails Guides. Now the community had a place to write and maintain official articles whose scope was defined by humans rather than code boundaries.
How about adding a Guides section to the website inspired by the Rails Guides, and encouraging community collaboration there, with frequent publishing of new versions? If I had a friendly place to submit PRs to, I would be very interested in contributing to something like this and seeing my ideas get reviewed and accepted or redirected to something better.
Yes this is a great idea. A general intro is badly needed
I’m pretty sure we don’t want to go down that path. Most people don’t find relish-style docs easy to follow for some reason, it’s just too…mechanical? OTOH we’ve never actually tried it. My opinion is just based on my own experience while reading relish docs (which I do on a regular basis as I’m a big RSpec user, who never remembers its matcher syntax lololol) and talking to folks about it every now and then.
My main issue is that you need full-blown executable examples. This will be too much in many cases. That’s why I’ve had an idea for a long time, that in a perfect world we would have a way of presenting code examples in tab-based widgets. Then you’d have “Example” tab and “Full source code” tab. This way you could see the essential stuff w/o any boilerplate setup.
Absolutely, in my task list above I skipped guides just because I’m now very single-gem-focused but you are right - high-level guides will probably have the biggest impact right now. I’m also sure that for contributors, writing such guides will be much simpler than focusing on a single gem and its features one-by-one
I’m more than happy to jump straight into this first. Like you mentioned, existing user docs aren’t too bad and guides are non-existent. I can add “Guides” to the top-level menu with a basic structure for adding stuff. It’d be hidden initially while there are no guides written, but it would be the first step.
I notice that early dry-rb adopters have much experience through many design concept like Dependency Injection, Module Builder Pattern, instances’ configuration is better than class constants,… things like that.
But for the large audience, who only know rails-way, they usually have unbelief with unfamiliar things.
I also feel hard to collect resources to educate/convince colleagues about this.
What can we offer to help people cross that chasm?
I think a collection of articles or introduction documents will help them see the good practices dry-rb is promoting.
Consider Asciidoc for the format, which would allow for a standard method of inter-document linking and other features, plus easy conversion to other formats. (GitHub previews Asciidoc as formatted HTML in PRs etc. just like it does Markdown.)
Beyond setup, the first editorial job is to compile a list of known target topics:
high level concepts people don’t quite grok, such as how the various gems relate to each other or the relevant Ruby basics, etc.,
frequently asked questions or frequently answered answers,
use cases that can be discussed in focused documents,
other subject areas that would make sense as guides or part of a guide.
Triaging this could be as simple as applying a “guides” tag to GitHub issues and/or forum discussions that seem like relevant guide fodder.
I feel like a diagram or visualization would be really powerful here that shows the current dependency graph, eg: Dry::Struct relies on Dry::Types so these are implicitly linked as a core knowledge area. But I could also see it designed as a sort of pairing visualizer: eg, Dry::Container goes quite well with Dry::AutoInject; or spice it up a notch with Dry::System
I agree with your complete statement @tiev and the quoted bit is probably too much to try to tackle here, but I do think that having some type of projects section, might be a nice way to introduce people to some of these architecture patterns, and the challenges they solve in a pretty concrete way.
Are you suggesting we should do it outside of our existing setup? I’ve evaluated https://antora.org/ some time ago and it’s exactly what we need, unfortunately the estimated effort that would have to go into rebuilding our website with all the docs using Antora/Asciidoc seemed to be huge. It would be good to stick to what we have unless somebody can step up and actually port everything to Antora (which would be amazing, but again, this is probably a bigger effort).
An intro document would be a fantastic start. That’s also why I think that splitting gems into tiers should help.
This could be a nice reference, because most certainly it needs to be improved (I used MindNode which isn’t the best tool for the job here).
I’ve left out dry-equalizer because we’re in the process of moving it to dry-core (it’s been moved already but we haven’t updated all the things yet to reflect this change).
For Rails-oriented devs, focusing on dry-rails should be the way to go - it’s the official integration with conventions that are provided by the railtie. It pre-configures various gems for you so getting started with stuff like dry-validation is quite simple. I wanted to add more features to this railtie but I haven’t found the time so far. At the moment I no longer work on a rails app so I put it on hold, personally. Once I’m working on a rails app again (which may happen soon), I’ll most likely go back to working on dry-rails.
Right, for both GitHub and forum tagging I was saying that tagging would be an efficient way to capture user questions and ideas, and committer answers and ideas, that seem like potential guide fodder.
I’ll have to look at the existing setup, but a standalone directory of .adoc files could be a very reasonable start that shouldn’t be very difficult to tack on to something. I can’t fully commit to it yet but I would enjoy working on an Antora transition. Interested in scoping that out for sure.
We’ve come a long way since dry-rb has been established in 2015 and I’m really proud of what we’ve achieved together. All the gems provide a lot of very powerful features; furthermore, due to the nature of dry-rb you can compose gems into more powerful abstractions.
I also think that spending some time on the technical ground-work is important - ie if we had a nice system for code example verification we wouldn’t waste time on reviewing things manually, dealing with mistakes that people report (which always happen) and so on.
One article/idea I had as a start is basically “Here are the things you should know about Ruby when working with Dry”. As an example, dry leverages 
