cross-link Kinto docs to Cliquet docs instead of copying

[glasserc]

Use the Sphinx "intersphinx" plugin to link to Cliquet documentation in a disciplined way rather than just copying a random amount of documentation out of another project. Most of the Kinto documentation should be defined with reference to corresponding documentation in Cliquet -- for example, Kinto permissions should link to Cliquet permissions, and Kinto records should link to Cliquet resources.

[N.B. that of course this might depend on the outcome of https://github.com/mozilla-services/cliquet/issues/687.]

[almet]

We've actually decided to do this on purpose, to have all the docs in one place without having to lose the user between cliquet and kinto goal was to not talk at all about cliquet in the kinto docs, hence the copy.

That being said, I'm not against a change in this. Just wanted to let you know why we made the decision when we did.

[glasserc]

Who is the intended audience for the documentation? My guess is that the main people who read Kinto documentation are going to be programmers who are intending to build software using Kinto. In that case, they're probably already going to be looking at documentation in two places: the main Kinto documentation, and the documentation for whatever library they are using in their own programming language. Is three places much worse than two places? It's not like the user would have to exert any extra effort to go to the Cliquet docs -- they would just click a link.

Software developers are normally very good at understanding that software is built on top of other software, and other libraries don't try to hide this (for example, the React tutorial refers to Markdown and the third-party marked library). So I think the conceptual cost is low. I think we would just need a note at the front saying that Kinto was built using the Cliquet protocol or something like that.

Instead, to avoid this conceptual cost, we're adding a lot of complexity to our documentation. In particular:

• Our documentation is duplicated across two projects. Both Kinto and Cliquet have information about what API endpoints you can use to set permissions, for example, and both have to be maintained.
• It isn't clear which version of this documentation is authoritative. For example, the Kinto documentation doesn't say you can update the data and permissions of a record at the same time, but the Cliquet documentation does. Which is right?
• Cliquet documentation has to be "relocatable", so it can be included in other projects. Since we don't include the entire Cliquet documentation into Kinto, some links in the Cliquet documentation (which point to other Cliquet documentation) are broken in the Kinto documentation (because we don't include the targets of those links in the copy). Maintainers of Cliquet documentation will need to always remember that some parts of their documentation serve not just as Cliquet documentation, but documentation of Cliquet-based services. I think this is going to make maintenance of Cliquet documentation much more challenging.

I believe that on balance, these disadvantages outweigh the advantage of having all the Kinto documentation in one place. I think it's possible to make both Cliquet and Kinto documentation more usable by providing overviews and Kinto-specific notes in the Kinto documentation, while linking to the Cliquet documentation for more details.

[Natim]

the Kinto documentation doesn't say you can update the data and permissions of a record at the same time, but the Cliquet documentation does. Which is right?

Both are right, yes you can update both at the same time.

I think this is going to make maintenance of Cliquet documentation much more challenging.

For sure.

[almet]

Hey @glasserc, and thanks for taking the time to advocate your solution !

I do agree that the current solution has shortcomings, and that we should solve them :)

It isn't clear which version of this documentation is authoritative.

Our goal then was to not have Kinto users ever exposed to the cliquet documentation. As a result, the Kinto docs should be authoritative.

[...] both have to be maintained.

This isn't completely true: the process is automatic. The docs are canonically stored in the cliquet documentation, and copied when Kinto documentation is generated.

Links are broken

That's a true challenge, and I believe that's where the pain-point really is.

---

The main goal we had with doing the copy was to not lose our users between the different documentations, and not have to duplicate the parts of the documentation which are similar between Cliquet and Kinto.

I've read your argument stating that developers are used to read many different documentation. I believe the problem here isn't related to the number of different documentation, but to the role each documentation has to play.

The distinction between Cliquet and Kinto is hard to make even for us developers, so preventing our users from doing it is IMO a sane thing to do.
Changing the naming from Cliquet to Kinto-Core kinda makes this hassle disappear, so we might consider it.

By doing so, I believe the number of concepts we expose to Kinto users are better delimited: we don't care to have them know about cliquet, we want to them to know about buckets, collections, records and permissions.

[leplatrem]

Looks like we're done with this ;) Cliquet now became kinto.core!