Modernize documentation for replication

[Fluxx]

I went through the README and updated its documentation to be a little richer, more exhaustive and also talk about the emerging replication branch. This is very much a draft, so there are likely spelling and grammar errors. Please point those out but do expect them.

[ivanov]

thinking about it more, though I kind of liked the Capitalization of Proper Nouns in the beginning of this, it's also distracting in that I find myself reading those terms differently. Not a big deal, at all, probably not worth going through and making it consistent. Leaving it all lower-cased but adding links to the relevant sections might be another way to go (more tedious to write and read in raw text, but more readable in rendered form)

[Fluxx]

thinking about it more, though I kind of liked the Capitalization of Proper Nouns in the beginning of this, it's also distracting in that I find myself reading those terms differently. Not a big deal, at all, probably not worth going through and making it consistent. Leaving it all lower-cased but adding links to the relevant sections might be another way to go (more tedious to write and read in raw text, but more readable in rendered form)

Yeah I hear you. I like to capitalize the proper nouns to help signify that the words refer to an actual thing and not just a concept. For example, it's good to know that the "Replication system" means an actual system in PGShovel vs the "replication system" which is more ambiguous.

[ivanov]

:+1:

[Fluxx]

@tkaemming I would really like to get your review if you have time since these are important words that we need to get right. If you can't get to it soon, a reply with an ETA on when you can would be great.

[tkaemming]

thinking about it more, though I kind of liked the Capitalization of Proper Nouns in the beginning of this, it's also distracting in that I find myself reading those terms differently

I had the same experience. I also found it confusing when plural terms were made proper nouns ("Replication Set".) At a high level, I also worry about the "Concepts" overview being too detailed (focusing on the components themselves, rather than the interconnections between them.)

I also have some wording and stylistic changes, but I will save those for a later patch rather than trying to shoehorn them in here.

Also, worth noting that one of the code blocks does not render correctly: https://github.com/disqus/pgshovel/blob/ff4f630273ea3d86ac319bb82eca230d99dfeb3d/README.rst#running-a-relay

[Fluxx]

I had the same experience. I also found it confusing when plural terms were made proper nouns ("Replication Set".)

Hmmm...well given that both of you felt the capitalization was distracting, I'll remove it.

At a high level, I also worry about the "Concepts" overview being too detailed (focusing on the components themselves, rather than the interconnections between them.)

Just to come full circle, as I mentioned above I will break up the sections of the README into an overview and then detail to help alleviate this.

also have some wording and stylistic changes, but I will save those for a later patch rather than trying to shoehorn them in here.

Any preview I could get on that to keep in mind? As I will be doing a lot of editing on this tomorrow.

Also, worth noting that one of the code blocks does not render correctly:

Ah thanks. I hadn't actually looked at the rendered version yet, but plan to do that once I'm closer to final draft to make sure everything looks good.

[Fluxx]

@ivanov last chance today to review, otherwise I'm gonna merge.

[tkaemming]

This is cool, lots of improvements. :+1: