Revise documentation to better describe API layers
jessegrosjean opened this issue · comments
First, thanks again for all this work!
Second I'm going to dwell on the non-perfect parts of automerge-swift experience (for me), but generally it seems to do what I want and I plan to use it... (assuming I can ever actually progress my own app code far enough). I'm not sure that I've ever followed an open source projects development quite so closely. I love the core, and also can't wait for more packaged versions of the networking stuff. The local-first architecture enabled by automerge really excites me.
My general thought is that I wonder if automerge-swift is trying to do too much. When I first started looking at the package I was expecting expecting something along the lines of Document Data Model, but with a Swift API.
Then I started reading the Five Minute Quick Start and got very confused. It didn't look like JSON, there was this new concept of encoders. The code didn't fit the JSON automerge model that I was expecting. Also I wasn't sure what to do with AutomergeText. I wondered if maybe lists and maps weren't yet supported by Swift wrapper.
Once I realized that those things were all extras built over the Document everything got much easier to use and understand. I think these extras might be useful, but I feel they also distract from the core of what automerge does and how it can be most efficiently used.
Small issue, but I'm also unsure about adding Observable to Document. I understand it makes working with SwiftUI easier, but it also (to me) distracts from the core API. I'm not sure it can scale usefully if your document has many items, it seems to lead API in wrong direction. Adds a new concept that isn't really core to automerge. I think of automerge more like a magic data structure, that does diffs and patches, and application code is responsible for wrapping those changes up into events.
Should you actually change anything? Very possibly not :) Extracting package seems like a lot of work to me, and it doesn't really affect functionality. I would maybe add a somewhere early in the documentation (such as in Five Minute QuickStart) that there are two levels of API in the project... use Document directly for low level API.
What I'm really interested in now is the network stuff, so I hesitate to post any of this and possibly slow you down. :/
Thanks,
Jesse
Thanks @jessegrosjean - love the feedback, and I'll definitely work to capture more before taking any big specific actions like splitting things up. That said, I'll definitely work on improving the documentation to make it clear there's two levels of API in this package, well - after I finish up the work on the automerge-repo and peer to peer syncing support that I've been working on in the demo app.
related feedback: #86
@jessegrosjean If you're inclined, I'd love you to take a look at the proposed updated documentation in #127 - I included instructions in the PR for pulling it down and building it in Xcode directly, as I don't have a location to publish it (the GitHub pages are hosting the current set), but if that would be significantly easier for you, I can arrange a fork of the repo somewhere with a link to read through.
I just finished a first pass, and it's probably full of typos and errors, but I thought I'd let it sit a few days and then come back with an editing eye to fix up any terrible flubs along those lines.
I think the API layers section helps a lot and would have solved my initial confusion.
Few random thoughts:
"The lowest layer lets you interact with the Automerge document" it's a mouthful, but maybe "cross platform" could fit in there somewhere... "The lowest layer lets you interact with the cross platform Automerge document API". Not really that important.
In the section Using the dynamic schema > Document-based Model I would remove the discussion of AutomergeText. That confuses me, because I understand that section to be about the core API. Leave AutomergeText discussion to custom coder discussion.
I'm not sure if the transferrable conformation for automerge documents should be listed as an API layer. Seems less important to then the other layers to me and could just be mentioned in Saving, loading, section.
Hope that helps
Awesome feedback @jessegrosjean , thank you!