dry-rb / dry-rb.org Goto Github PK

We currently redirect www.dry-rb.org to dry-rb.org so we need to add canonical link tags pointing to dry-rb.org

TODO

• add a section about predicate logic
• add a section about macros
• add a section about option + with APIs
• add a section about using constrained types for reusing validation rules
• add predicate usage examples

A number of queries and confusion raised on the gitter room seem to be caused by people using the examples and guidance on the dry-rb site with an older version of a gem.

IMHO, a lot of this confusion could be addressed if it was easy to view the docs that relate to the version of the gem you are using. @timriley suggested something like bundlers website.

The other benefits:

• we can update the site with changes on master as we go rather than holding off until a gem release.
• the history of the gem & its docs is easily accessible in the site.

On the home page, we display a couple of examples.

Replace the one of dry-monads with one example of dry-transaction

This issue follows the one here dry-rb/dry-validation#309 (comment).

The validate and option methods are not present on the website.

Right now it's a copy/paste from original README. It would be good to split it up into sub-sections and provide more info and context.

TODO

• Improve intro section, explain the differences between dry-rb solution and heavy IoC frameworks
• Explain how it's used along with dry-auto_inject and dry-component, add links to example apps
• Split it into smaller sections
• Add a sub-section about stubbing, explain best practices, dos and donts etc.

• dry-container
• dry-configurable
• dry-auto_inject
• dry-equalizer
• dry-component
• dry-logic

in page https://github.com/dry-rb/dry-rb.org/blob/master/source/gems/dry-validation/high-level-rules.html.md there is something that seems incorrect:

rule(barcode_only: [:barcode, :job_number, :sample_number]) do |barcode, job_num, sample_num|
  barcode.filled? & (job_num.none? & sample_num.none?)
end

is put as an example of "validating absence of job_num and sample_num when barcode is filled". But to me the code sounds as "validating absence of job_num and sample_num and barcode is filled". Maybe it was supposed to be as follows?

rule(barcode_only: [:barcode, :job_number, :sample_number]) do |barcode, job_num, sample_num|
  barcode.empty? | (job_num.none? & sample_num.none?)
end

Right now we only have a list of the predicates, this needs more explanation with code examples.

We should probably change the colour of comments in code blocks, they are really hard to read on mobile and could be clearer on desktop

While reading the documentation of dry-validation i stumbled upon some things that seem stange to me:

• What's good_input handed to schema.call() in section none??
• In section eql? should it be assert input[:sample] == 1234 instead of assert sample[:input] == 1234?
• Again, good_input in section type? instead of just input?

You can see it here with the extra space before require:

Would be great to have a dedicated section where we document info about contributing

Things I'd like to see in this section (random order):

• Info about writing tests
• Info about CodeClimate and how we use metrics
• Info about versioning scheme
• Info about issues, labels and how to find a task to work on
• A CoC or a statement that we have a CoC and a link to it
• A list of current contributors
• ???

Makes sense? WDYT?

Within the site structure right now, one of the more important roles of the community page is to point people to the various places they can interact with the dry-rb community and get help (i.e. the discussion forum, GitHub issues, and Gitter chat). Those links are kind of hidden right now though, tucked away within the text paragraphs.

I think it'd be good to rethink this page a little given its most important role really is to show site visitors where they can go to interact with the dry-rb community. I think we could probably:

• Properly highlight the 3 community interaction points. Perhaps pull them out into their own section where each one is a big text/image/link combo, easy to see and click.
• Correspondingly, deemphasise the core team listing a little. It feels like it's a little big right now.

Refs dry-rb/dry-types#174

It currently redirects the user away from the site, should we use a blank target?

This is a great way to help people contribute by fixing some mistakes in doc pages

We should allow a click on any part of the blog post previews on the homepage to take the user through to the full post's page.

Along the lines of #59, it'd be structurally more beneficial if the dry-rb ecosystem started following SemVer. Personally, what matter most are the API changes parts. It's understandable for an open-source and a nascent project to keep changing without proper notification and documentation. SemVer here will helps us (in the outside) be in control of how much exposure to changes we want in each project we work on.

I sadly know that takes away the sexy 1.00 milestone. But hey, this way you're more agile which is still sexy, I hope.

P.s. I didn't know where to post this issue so I hope I made the right call by submitting it here. Cheers.

Passing additional step arguments in the basics section has old arguments order:

http://dry-rb.org/gems/dry-transaction/basic-usage/

It's a bit awkward right now. The dots seem small and very far away, and the space above a list is greater than the space below it.

The current dry-rb.org homepage could do better to introduce people to dry-rb and entice them to try it.

I’d like to make this better. I think an improved homepage could offer:

• A more compelling one-line pitch
• A better statement of our founding principles (replacing the mostly-empty non-intrusive/flexible/fast section on the current site). This could go 2 ways, I think: either collapse these into a single, supporting sentence (or two) to the one-line pitch, or try and expand on these as multiple separate points with a supporting sentence for each. These'd need different design treatments, obviously. I think perhaps the "supporting sentence" might be better, and we can link off to a full "principles" page later if we wanted to.
• A description of the 2 possible “pathways” you can follow in adopting dry-rb:
  1. dry-rb as foundation of your app (“go all in”)
  2. or to enhance parts of your existing app (“pick and choose”)
• Short code examples for a few important use cases
  • validation
  • types?
  • dry-system + auto_inject
  • dry-monads + matcher
• Big fat links/buttons to the list of gems + (upcoming) guides page

In doing these, I think we could probably ditch the gem list on the home page and just make the /gems page better (will file a separate issue about that).

What's the work involved here? Obviously there's some content to be written, but I think at the same time we could start work on some new visual design structure to house it.

FWIW, I surveyed some other OSS project homepages in thinking about this:

Ember.js: probably the best example of the kind of thing I’d like to see us have. Visually nice and still has a decent intro and code samples.

React: less visually impressive than Ember but a decent combo of intro pitch + code examples. This is probably closer to what we have now and wouldn’t be a bad place to get to :)

Angular: So… material. TBH this feels a little light-on for a homepage. I’d rather us supply visitors with some more info.

Mithril: Not visually impressive, but it has a clear little “pitch” section up-front, which isn’t bad.

Ruby on Rails: This is a bit light on details, which Rails can get away with, but we need to give more info to get people to consider dry-rb, IMO. Also, I’m not sold on the video as introductory material. Most times I won’t click.

Otherwise switching between gem docs takes 1 click more

It would be nice for the site to build itself whenever changes are pushed to master.

Right now there's no way to get from a gem's page on the dry-rb site through to its source code, issues, etc. on GitHub. I think we need to make this a fairly prominent link somewhere. Something with a special style at the bottom of each gem's navigation menu, perhaps?

Is there anything we can do to improve readability and tighten things up a little?

We want to encourage people to use this gem in the way we intended, which is with a real container (not a hash!) and with objects already built to return Either results.

Discussion about alternative usage (such as alternative containers and the step adapters) can be moved into a different section or further down the page.

We're using webkit rules

• explain hash schema types (maybe a table with difference would be helpful?)
• explain how summing schemas work (esp address dry-rb/dry-types#158)
• explain how defaults are applied

As you can see, this link http://dry-rb.org/gems/dry-validation/input-preprocessing/ lead to a 404 page.

Right now, when you <em>something</em>, it doesn't show as italicised. Ideally it would :)

Currently the gem page titles are the same as the h1 tags, it would be good to indicate which gem docs you're reading

The gems page is pretty barebones right now. If we pull the "highlighted gems" off the home page in #133, we'll need a better place to showcase them. I'm thinking we could do the following to improve the gems page:

• Add a "featured gems" area for the popular/important ones
• Do something to make the full listing look a bit nicer. Fatten things up, offer links to both docs and source code, maybe even relevant guides with dry-rb.org (once we add them).

The site currently doesn't have a favicon and the page titles aren't indicative that the tab is on the dry-rb.org site

This would be a nice UX improvement since people won't have to scroll to jump to a different section and the title of the current page will always be visible at the top.

Right now the text wraps underneath the dot point, when it should be indented and left aligned.

Is there also too much spacing to the right of the dots?

webpack is appending shas to file names, but retina.js tries to fetch images with naming structure looking like that: [email protected] whereas the file is called [email protected]