# Documentation - help wanted!

**URL:** <https://discourse.dry-rb.org/t/documentation-help-wanted/1212>\
**Category:** Announcements\
**Created:** [March 9, 2021, 9:50am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212 "2021-03-09T09:50:47Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![solnic](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/solnic/32/779_2.png) [@solnic](https://discourse.dry-rb.org/u/solnic)\
**Post date:** [March 9, 2021, 9:50am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/1 "2021-03-09T09:50:47Z")

</div>

Hey y’all!

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:

- All gems have user documentation on [dry-rb.org](http://dry-rb.org)
- Most gems have decent API docs on rubydoc.info
- 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](http://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!

Cheers!  
solnic

---

<div class="post-metadata">

**Author:** ![ianks](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/ianks/32/449_2.png) [@ianks](https://discourse.dry-rb.org/u/ianks)\
**Post date:** [March 10, 2021, 1:56am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/2 "2021-03-10T01:56:46Z")

</div>

Count me in!

---

<div class="post-metadata">

**Author:** ![diegotoral](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/diegotoral/32/568_2.png) [@diegotoral](https://discourse.dry-rb.org/u/diegotoral)\
**Post date:** [March 10, 2021, 11:18am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/3 "2021-03-10T11:18:07Z")

</div>

I am here to help!

---

<div class="post-metadata">

**Author:** ![debashis-biswal](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/debashis-biswal/32/614_2.png) [@debashis-biswal](https://discourse.dry-rb.org/u/debashis-biswal)\
**Post date:** [March 10, 2021, 5:22pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/4 "2021-03-10T17:22:20Z")

</div>

I am here to help.

---

<div class="post-metadata">

**Author:** ![buszu](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/buszu/32/615_2.png) [@buszu](https://discourse.dry-rb.org/u/buszu)\
**Post date:** [March 10, 2021, 7:16pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/5 "2021-03-10T19:16:09Z")

</div>

I’d be happy to help if will manage to in my free time.

@solnic is there any starting point? Any todo list of undocumented features to be documented? Any list of docs to be improved?

---

<div class="post-metadata">

**Author:** ![solnic](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/solnic/32/779_2.png) [@solnic](https://discourse.dry-rb.org/u/solnic)\
**Post date:** [March 11, 2021, 6:28am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/6 "2021-03-11T06:28:46Z")

</div>

> [@buszu](#):
>
> @solnic is there any starting point? Any todo list of undocumented features to be documented? Any list of docs to be improved?

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.

---

<div class="post-metadata">

**Author:** ![jedschneider](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/jedschneider/32/617_2.png) [@jedschneider](https://discourse.dry-rb.org/u/jedschneider)\
**Post date:** [March 11, 2021, 3:41pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/7 "2021-03-11T15:41:10Z")

</div>

👋 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.

---

<div class="post-metadata">

**Author:** ![jedschneider](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/jedschneider/32/617_2.png) [@jedschneider](https://discourse.dry-rb.org/u/jedschneider)\
**Post date:** [March 11, 2021, 3:46pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/8 "2021-03-11T15:46:12Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![replaid](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/replaid/32/619_2.png) [@replaid](https://discourse.dry-rb.org/u/replaid)\
**Post date:** [March 11, 2021, 5:16pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/9 "2021-03-11T17:16:17Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![solnic](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/solnic/32/779_2.png) [@solnic](https://discourse.dry-rb.org/u/solnic)\
**Post date:** [March 12, 2021, 7:10am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/10 "2021-03-12T07:10:18Z")

</div>

> [@jedschneider](#):
>
> 👋 One article/idea I had as a start is basically “Here are the things you should know about Ruby when working with Dry”

Yes this is a great idea. A general intro is _badly_ needed 🙂

> [@jedschneider](#):
>
> 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 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.

---

<div class="post-metadata">

**Author:** ![solnic](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/solnic/32/779_2.png) [@solnic](https://discourse.dry-rb.org/u/solnic)\
**Post date:** [March 12, 2021, 7:18am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/11 "2021-03-12T07:18:49Z")

</div>

> [@replaid](#):
>
> 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?

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 🙂

> [@replaid](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![tiev](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/tiev/32/299_2.png) [@tiev](https://discourse.dry-rb.org/u/tiev)\
**Post date:** [March 12, 2021, 9:09am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/12 "2021-03-12T09:09:07Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![replaid](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/replaid/32/619_2.png) [@replaid](https://discourse.dry-rb.org/u/replaid)\
**Post date:** [March 12, 2021, 9:31am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/13 "2021-03-12T09:31:26Z")

</div>

Excellent!

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.

---

<div class="post-metadata">

**Author:** ![jedschneider](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/jedschneider/32/617_2.png) [@jedschneider](https://discourse.dry-rb.org/u/jedschneider)\
**Post date:** [March 12, 2021, 4:40pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/14 "2021-03-12T16:40:51Z")

</div>

> [@replaid](#):
>
> high level concepts people don’t quite grok, such as how the various gems relate to each other or the relevant Ruby basics, etc.,

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 😉

---

<div class="post-metadata">

**Author:** ![jedschneider](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/jedschneider/32/617_2.png) [@jedschneider](https://discourse.dry-rb.org/u/jedschneider)\
**Post date:** [March 12, 2021, 4:46pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/15 "2021-03-12T16:46:35Z")

</div>

> [@tiev](#):
>
> I also feel hard to collect resources to educate/convince colleagues about this.

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.

---

<div class="post-metadata">

**Author:** ![solnic](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/solnic/32/779_2.png) [@solnic](https://discourse.dry-rb.org/u/solnic)\
**Post date:** [March 13, 2021, 3:36pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/16 "2021-03-13T15:36:19Z")

</div>

> [@replaid](#):
>
> Consider Asciidoc for the format

Are you suggesting we should do it outside of our existing setup? I’ve evaluated [https://antora.org/](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).

> [@replaid](#):
>
> Beyond setup, the first editorial job is to compile a list of known target topics:

An intro document would be a fantastic start. That’s also why I think that splitting gems into tiers should help.

> [@replaid](#):
>
> Triaging this could be as simple as applying a “guides” tag to GitHub issues

Right, we should use [Issues · dry-rb/dry-rb.org · GitHub](https://github.com/dry-rb/dry-rb.org/issues) for this type of issues

> [@replaid](#):
>
> and/or forum discussions that seem like relevant guide fodder.

You mean like going through the forum and marking existing threads as a source of inspiration for a guide?

---

<div class="post-metadata">

**Author:** ![solnic](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/solnic/32/779_2.png) [@solnic](https://discourse.dry-rb.org/u/solnic)\
**Post date:** [March 13, 2021, 3:41pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/17 "2021-03-13T15:41:42Z")

</div>

> [@jedschneider](#):
>
> I feel like a diagram or visualization would be really powerful here

I actually created such a diagram last year:

 ![Screenshot 2021-03-13 at 16.39.19](https://canada1.discourse-cdn.com/flex031/uploads/dry_rb/original/1X/55fd1a5875bc8b0a2cd8f902a26c5370bd3d834a.png)

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).

---

<div class="post-metadata">

**Author:** ![solnic](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/solnic/32/779_2.png) [@solnic](https://discourse.dry-rb.org/u/solnic)\
**Post date:** [March 13, 2021, 3:46pm UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/18 "2021-03-13T15:46:21Z")

</div>

> [@tiev](#):
>
> But for the large audience, who only know rails-way, they usually have unbelief with unfamiliar things.

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`.

---

<div class="post-metadata">

**Author:** ![replaid](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/replaid/32/619_2.png) [@replaid](https://discourse.dry-rb.org/u/replaid)\
**Post date:** [March 15, 2021, 9:19am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/19 "2021-03-15T09:19:20Z")

</div>

> [@solnic](#):
>
> > [@replaid](#):
> >
> > Triaging this could be as simple as applying a “guides” tag to GitHub issues
> 
> Right, we should use [Issues · dry-rb/dry-rb.org · GitHub](https://github.com/dry-rb/dry-rb.org/issues) for this type of issues
> 
> > [@replaid](#):
> >
> > and/or forum discussions that seem like relevant guide fodder.
> 
> You mean like going through the forum and marking existing threads as a source of inspiration for a guide?

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.

---

<div class="post-metadata">

**Author:** ![replaid](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.dry-rb.org/replaid/32/619_2.png) [@replaid](https://discourse.dry-rb.org/u/replaid)\
**Post date:** [March 15, 2021, 9:23am UTC](https://discourse.dry-rb.org/t/documentation-help-wanted/1212/20 "2021-03-15T09:23:15Z")

</div>

> [@solnic](#):
>
> > [@replaid](#):
> >
> > Consider Asciidoc for the format
> 
> Are you suggesting we should do it outside of our existing setup? I’ve evaluated [https://antora.org/](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).

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.

[Next page](https://discourse.dry-rb.org/t/documentation-help-wanted/1212.md?page=2)