Make explanation of "soft dependency" more clear

[Pictor13]

in the README.md, since it contained mistakes that made difficult to understand the concept.

I made it more verbose and repetitive of the grammar subjects, so that even a dumb like me can understand it 😉.
Also I added more markdown, according to my practices.

Please revise if:

• the explanation is solid clear
• there are conceptual mistakes (since I clarified my understanding of the terminology while fixing the README)
• there are grammar, syntax, punctuation errors
• the use of markdown is consistent with the author's practices

I think it's better now, but English isn't my mother language; of course I need external approval to be sure that clarity has actually improved.
So, please, criticize 🤓

[Ocramius]

Overall, I like the examples made, but I must say that we need to do a couple things:

1. move away from the require-dev example: a lot of people seem to be confused by it (see previous issues, if interested)
2. we probably want to remove the DBUnit example (it's dead-dead-dead anyway)

May I suggest if we rewrite it with an example like:

• I have a cache library
• my library works with both the filesystem and redis
• it only works with redis when redis is installed (soft dependency), but it crashes if redis is configured and not installed

Would that be a better example?

I want to make the example more evident, showing perhaps a code snippet where a library would experience a runtime hard-crash.

[Pictor13]

Yes I agree, thank you, that's a good input.

I personally only followed the impulse to improve the clarity for myself first, but didn't bother to improve the example; I've noticed DBUnit was archived, but I didn't know it nor CompserRequireChecker till today, so I didn't change much or diverge from what was already there.

I can't say if your example is better (more understandable) but for sure is more concrete and skips the reference to a dead repo.

By chance, do you know any library that would suit for the example?
I didn't check, but maybe Flysystem might be a candidate? (if not too complex)
Anyway some snippet would be better than a verbose explanation.

[Ocramius]

I would make an artificial example - no libraries, as that implies library knowledge

…

On Tue, Sep 29, 2020, 23:24 Igor Pellegrini ***@***.***> wrote: Yes I agree, thank you, that's a good input. I personally only followed the impulse to improve the clarity for myself first, but didn't bother to improve the example; I've noticed *DBUnit* was archived, but I didn't know it nor *CompserRequireChecker* till today, so I didn't change much or diverge from what was already there. I can't say if your example is better (more understandable) but for sure is more concrete and skips the reference to a dead repo. By chance, do you know any library that would suit for the example? I didn't check, but maybe Flysystem might be a candidate? (if not too complex) Anyway some snippet would be better than a verbose explanation. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#204 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABFVEEITYISNIYZEYN3OLLSIJF7NANCNFSM4R6BUACQ> .

[Ocramius]

Closing here. I think the discussion and contribution are valid, and #224 took this over with a well defined example 👍

[Pictor13]

Great, glad that @SvenRtbg completed this 🎉
It really improved the clarity of the explanation.
I'm sorry that I was too busy lately to rework it.