write simplified, less opinionated docs

[mixmix]

Hey @KGibb8 this is related to card https://trello.com/c/Ko8QOCOS/70-ssb-schema-validation-fixups

The motivation for these changes is a few things :

• there were undocumented uses (they were only exampled)
• the docs gave an example more complex than was needed for current use

I've addressed this by:

• adding a simple "example usage" section at the top with simplest possible use
• added an "API" section which clearly spells out (I hope) the moving parts
• added a link out to the detailed example (ssb-dark-crystal-schema!)

[mixmix]

you can see what the changed README renders like here : https://github.com/ssbc/ssb-schema-validation/blob/8613182302872d790e818f7b0bc48ae39fc647fd/README.md

[m4gpi]

Funny, I find your amendments to the README more challenging to understand as documentation than what I wrote. Different minds! As a new-comer, the project layout and simple isPost / isComment example feels like a useful simplicity. Wondering if an integration of the two then makes more sense (to help people of different mindsets)? I will merge the two into a longer README tomorrow with your section above, and my section as an example case below. It can't hurt to have simplified examples!

[mixmix]

I wrote something less opinionated and with less moving parts. If I recall your example had a hang over from the previous requirement for object layout still baked in. I'm look when I get to my laptop

…

On Wed, 9 Jan 2019, 00:37 Kieran Gibb, ***@***.***> wrote: Funny, I find your amendments to the README more challenging to understand as documentation than what I wrote. As a new-comer, the project layout and simple isPost / isComment example feels like a useful simplicity. Wondering if an integration of the two then makes more sense (to help people of different mindsets)? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACitnhY5HNsKM2GJG07nPCk_FL_k7qgFks5vBILogaJpZM4ZlGZg> .

[mixmix]

Yeah to clarify, your example used two different message types, which added unnecessary detail IMO. I stripped it down to a single example and removed the project structure because that particular details is up to the user to decide. The comprimise was a link out to our live example where they could copy our pattern from ssb-dark-crystal-schema if it was useful.

The other thing I added was explicity documentation of the methods and arguments they took. There were a couple of things you wouldn't know from the docs that were there about how to use some things.

Hmmm .. I feel like that's just putting in words what I tried to write in the original PR description.

---

For me, the non-negotiable is really the API documentation. The rest is preference, and while I think I'm right because I've been a teacher and like to think I know what good simple examples feel like, I'm ok just leaving if you're not into it.

[m4gpi]

I think my interpretation of simplest possible doesn't necessarily mean less explanation. I'm used to reading Ruby documentation which often comes with loads of examples and a suggested use / use convention, which I found when starting off really helpful when moving forward quickly. I've found some SSB and a lot of Node documentation lacking in that respect. So I like to make sure there's some clearly explained examples to make it easier to try out, rather than landing here and not necessarily knowing where to start. That's my own take on documentation anyway.

I agree with the only use one message type point. I've added a couple of extra sentences to flesh out the explanation. Thanks for the rewrite, the API documentation is really important!