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 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?
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
Yes totally but please let’s not talk about both dry and rom here because it’ll make this discussion harder
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!).
For them there is a key thing to understand: a pattern that separates deps and params and “functional objects” attitude. In my point of view this is a foundation of composing objects and injecting dependencies in dry-system.
The other things are that when we want to use dry-rails it would be good to know limitations first, I mean: try to make a perfect software but if you can’t afford honestly tell users what may be difficult or what’s not working. Apart from providing clear info it’s good for impressing users. So “known issues” would be welcome. E.g.:
not sure how dry-rails would play with ActiveRecord. I know it integrates well with Sequel,
turning off finalizing application in rake tasks and booting components in isolation,
spring and not seeing (refreshing) components.
Besides, some real-life use cases would be good and clarifying choices/difference between:
constants vs. abstract components,
safe params and contracts,
contracts and AR/AM validations (I suppose more monolith developers would use dry-validation if there would be an official guide for binding contracts to forms (for Rails’ form_with),
Rails initializers vs. dry-system’s bootables.
dry-validation is very easy to use in Rails w/o dry-rails (it’s even easier) and the rest of the railtie is mainly dry-system that has few own conventions. When documenting, the relation between dry-system and dry-rails should be clear (how we do it in standalone dry-system, how we do it in Rails`).
Last but not least (and maybe the most important) - setup docs. dry-system and it’s railtie have both very nice boundaries between might and magic - mostly driven by configuration but some conventions are there as well. Devs should know what to place where, what needs to be configured and what is ‘just available’. I would consider “user journey” structure:
I want to setup skeleton app, so…
I want to add db, so…
I want to add rake tasks for the db, so…
I want to add background jobs, so…
etc, where clear instructions like “add this gem, add config in this file, setup this here” come after “so”.
With my Hanami Mastery initiative I am creating a semi-commercial project supporting Hanami RB and libraries it depends on - fortunately the whole DRY-RB and ROM-RB families are included!
As I’ve started with help on official Hanami Guides, I’ll be able to work on DRY-RB guides and documentation too.
I’ve started covering all of the DRY-RB gems in HanamiMastery episodes, publishing extensive articles with real-world usage examples, and the connected Youtube tutorials.
The great documentation is a MUST to get to the next level of adoption. So far I see mid-senior people interested in DRY-RB mostly, and only those who experience problems with The Rails Way.
As my project is correlated to DRY/ROM/Hanami, it’s in my best interest to ensure there is amazing documentation and resources available for all those gems.
It means that over time I’ll possibly be able to dedicate FULL-Time just to improve and maintain documentation and create learning resources for DRY, ROM and Hanami.
I still prefer to configure dry-rb gems myself without any limitations and just add one after the other whenever I need one in Rails applications.
Dry-Rails seem beneficial to me only for having built-in code reloading configuration and zeitwerk integration for dry-system.
So having this documented, would be also beneficial I think. Rails Devs got used to code being reloaded life, and it’s “weird” if the dry-system components require server restart.
@solnic I think Obsidian Sync could be also an alternative. It has A built-in Graph feature. We could build docs repository the same way we do currently, pulling documents from multiple gems on deploys.
BUT, just by listing the gem dependencies in one MD file in the gem’s repository, you can end up with something like this:
I agree with @solnic about dry-rails for Rails oriented devs.
I would suggest a documentation that have two parts:
For people that just start to learn about all the general concepts like DI. They need more direction into what are considered good patterns and why.
For those that are already familiar with the general concepts of DI but need specifics of this library approach. For example configuration, conventions, code examples.
I think there are some branches on GitHub with my antora experiments, I’ll try to find them.
for asciidoc.