We write specifications before we implement code for non-trivial changes, and that’s not the same as writing proper documentation – far from it. Then, as I explained code changes are broken down across several independent PRs which bear little resemblance to a high-level story. So indeed that tight commit-level relationship you suggest between code and documentation doesn’t exist today, and there’s nothing wrong with that.
No, I see a tight divide between what we have today and what is needed, and I’m willing to try different ways to fix that.
I explicitly said in our previous call about the topic that you should feel free to experiment with different ways to solve these issues.
That said, you may hear again from me if we don’t fix them. For example, in our last call we discussed the fact the gadget snap format documentation was immediately out of date, because its content was copied out of the real specification and separated into multiple reworded pieces. Of course, on the next change we’ve made to the specification the documentation was already out of date, and meaningfully so.
Then, to this day our specification documents the prepare-device hook, which is important in the context of the gadget snap. Unfortunately, the reference in snapcraft.io not only cut that part out, but decided to put that inside “Configuration hooks”, which is completely unrelated.
So, quick recap: documentation broken apart, reworded, moved into the incorrect context, made hard to synchronize with new changes. It would be many many times better, for you, for us, for people using it, if that specification was simply picked up, synchronized and rendered.
Hopefully we understand each other now. We’ll be making an effort to have good documentation here, and would appreciate your help on that.
Thanks for the conversation.