Hi all
I feel as though the Juju community could make it easier to people writing charms to provide more details about the ad hoc protocols sitting behind interfaces.
Here are 2 early drafts:
What is the next highest priority? At the moment, I think we should focus on tasks that are used heavily within HTTP-based microservices.
Is that a valid place to start?
Would it be better to submit these to the interface code in GH itself? Maybe work out a standard template that folks could use or work with the developers to see if that template would be useful as part of a “interface init” or the like in the future?
I worry that documentation so far from the code leads to quickly out of date documentation and a disconnect between finding the interface to use vs where the docs live for it.
Probably, especially if it matures. At the moment though, I don’t think so. Some of my thinking… sorry if it’s a bit disjointed.
The community needs a central location to iterate on how to document interfaces. No single code repository is that central location. So, in a sense, this is a mechanism for creating a “standard template” that works.
Having documentation here is a good way to route people to the correct code repository. I like the layer index. But how do people find the layer index in the first place? Why is it in the github.com/juju namespace, but the layers/interfaces are within the github.com/juju-solutions namespace?
Interfaces are not specific to a specific code base. They represent a contract between multiple code bases. Every provider and requirer is a stakeholder in the interface. Reactive layers have treated interfaces that way. I believe that’s why there is huge fragmentation. The current approach creates knowledge silos by design.
We will need to create a neutral space for transitioning towards the new charming framework. Coupling documentation to a code repository will make that transition even more difficult.
As a wider issue, I believe that we, as a Juju community, need to accept that developers want to build their own systems for writing charms. @maaudet and @zicklag are proof of that. Coupling an interface with a code repository limits the ability of people using multiple systems. They should be able to interact with charms that they trust, without importing code into their own projects that they might not trust.
Thinking again of the knowledge silos problem. Right now, every charm developer has their own way of documenting things, right down to the build system and layout. Most charms use a partially complete README, others use Sphinx, others have a custom Markdown-based system, …
Interesting idea: What if you had an “interface store”. Essentially a docs “store” where interfaces are designed and put up on the store which documents the interface. Each interface may be developed by whoever created the interface name, similar to a charm in the charm store. Obviously nothing would bind people to following those rules, but it gives a place for people to collaborate on accepted standards.
Maybe each interface would have a git repo like a charm would. That way people could collaborate on the interface?
Not sure if I like the idea myself or not.
The weird part about the whole thing is that there is nothing formalizing interfaces. They are just the concepts behind setting and getting key-value pairs and the procedures taken at different times and in response to different keys.
This I agree with. I’d love to see that libraries in the new framework have a central location to the library. However, I guess I just can’t get beyond that these feel like libraries and not total software projects with end user documentation but more “using this class” type docs that belong by and with the code.
I agree that finding the layer index isn’t done well and can use improvement but I’ll point out that the proposed docs page doesn’t link to the layer code or how to get it?
Actually now that I reread that I think I see your goal/point a bit more clearly. This isn’t documentation for the layer itself, but for the interface as we know/understand it. Interesting. What is the source of truth around an interface then?
This is a very good point! Will update. At this stage, those three pages represent sketches/drafts rather than final state.
The idea would be to explain use cases, triggers, expectations of units on both sides of the relation, as well as the technical details.
I don’t have a good answer for this. I’m hoping will emerge from bringing people together. At the moment, the “source of truth” is the reference implementation of an interface. But that’s not easy to introspect.
I think this is the fundamental question we have to answer.
Right now, whoever made the layer for that interface essentially gets to define what the rules around connecting across that interface is.
I think that starting out by documenting the interfaces as they are today on the forum is a good start. That way people can at least understand the interfaces more and it can stand in for a more permanent solution once we figure out what that might end up being.
I definitely felt like the interface documentation needed to be better defined when I tried to make a bash charm that connected to a PostgreSQL charm. Having a centralized place to find that documentation and a standard format would go a long way and save a lot of time.
