refactor README.md

[mixmix]

Motivation / Approach

for this : I wanted to read this in a way which was helpful for beginners. Taking from teaching, the idea I applied was "give me just enough detail to get started, then come back around with more detail as required".

So we start out very simple, then put more detail in the API section.

🔥 I also mutated the API to make things clearer

As I was updating this I stumbled across things which felt like they made telling the story harder.
Things like:

• API behaves differently for the root feed than for all other feeds. This means we have to write more things
• use of words which conflict with other modules in ecosystem: feedtype is actually more like BFE format

I've commented those with 🔥 so we can discuss.

Andre I could have split that out into a different PR but I was writing from the point of view of ideal end state. Lets decide what we want then mutate this PR to end up where we want to be

[mixmix]

Rendered README

https://github.com/ssbc/ssb-meta-feeds/blob/04d9b8e59636b35b852fc07d97b1fa5fac0dfdf0/README.md (outdated)

[mixmix]

wrote and explicit signature documentation for this special usage to make it clear.
I think this should be moved down in the docs

🔥
I disliked that the object you got back from this call of this method was different, so I made it isomorphic:

• metafeed: null
• feedpuprpose: 'root'
• feedtype: 'bendybutt-v1',
• metadata: {}

NOTE I think we should change feedtype to format

[mixmix]

addressed in #62

[mixmix]

🔥 is this true?
This current signature really suggests you can use this on other peoples feedIds too....

[mixmix]

@staltz have addressed all comments. thanks for review

Do you want to re-review, or shall I merge?

[mixmix]

lol... changes README, tests fail D:

[staltz]

have addressed all comments. thanks for review

Do you want to re-review, or shall I merge?

@mixmix Let's merge, but I'll make a follow-up PR to recover some of the text you deleted, like under the "Example usage" section, there was quite a good amount of explanation and hand-holding that shouldn't be deleted.

As a general rule that arj and I have been following, the PR author merges only after the PR reviewer has approved with a green checkmark. Any moment before that is considered "don't merge yet".