Documentation - help wanted!

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.

2 Likes

Yes this is a great idea. A general intro is badly needed :slightly_smiling_face:

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.

1 Like

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 :slightly_smiling_face:

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.

1 Like

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.

3 Likes

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.

1 Like

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 :wink:

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.

2 Likes

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.

Right, we should use Issues · dry-rb/dry-rb.org · GitHub for this type of issues

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

I actually created such a diagram last year:

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

2 Likes

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.

1 Like

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.

1 Like

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.

It’s middleman + middleman-blog + my hacky solnic/middleman-docsite extension that allows us to pull docs from external repos into the main dry-rb.org repo (amongst other stuff). This is essentially what Antora provides OOTB. The current setup is OK but we need to maintain it, which I do not like.

I’d be OK with that but assuming we’d all agree that we want to move to Antora with everything eventually (and even that wouldn’t guarantee that we’d really do it hah!). The last thing we want is two different setups for our docs.

Anyhow, converting docs won’t be too hard, there are tools which can do md => .adoc but converting templates with HTML/CSS and so on would be a major PITA, at least for me :slightly_smiling_face: I think there are some branches on GitHub with my antora experiments, I’ll try to find them.

I’m happy to start on this, seems like a great place to start. Would it make sense to start another thread to collect the ideas that should go into that intro?

Sweet! Yes please create a new thread under Ideas category :slight_smile:

For me personally, the actual format (i.e. markdown vs asciidoc) is the least important thing here.

I think the first thing we should do is a general survey about biggest pain points with documentation, and address those.

Overall I think the DRY docs are pretty damn solid. At least, having used the gems in production for years, we haven’t run into too many issues. There could probably be some reorganization, and maybe some discoverability about “when to use the dry-foo” gem.

I think the ROM gem docs are the ones that need the most love, since there is so much amazing functionality that’s being undersold since you often have to source dive to find the features.

This resonates for me. Both projects would benefit from more examples covering different aspects of the APIs, but its more acute in ROM given that you have to understand more of the parts to be productive with it.

Also would ROM benefit from moving to Antora? And would that simplify maintenance across both projects more?

I agree that this doesn’t seem to be like a priority right now and I’d just keep it as something to do in the future.

This is a great idea - are you talking about something like a google form just shared publicly so that people can express their opinions?

I actually think dry-rb docs are decent from an existing user pov who already knows a thing or two about the gems. If you look at it from a newcomer point of view though…then it’s probably not that great :slight_smile:

Yes totally but please let’s not talk about both dry and rom here because it’ll make this discussion harder :sweat_smile:

Like I mentioned, let’s try to keep rom out of this discussion but I’ll reply to this question because it applies to dry docs too. I think in the long term moving to Antora would make a lot of sense because it provides the type of functionality we really need and it works OOTB. It seems like moving to Antora would be a big effort though and for now our current setup does the job quite alright. That’s why I mentioned somewhere above that we could consider making the big switch already only if we could be more-or-less certain that we have somebody who has the time and motivation to Just Do It™. It’d be a shame if we started the process and leave it half-done because somebody lost interest/no longer has the time/etc. which can totally happen (OSS reality!).