Maybe I've been out of the game or something. But I don't think saying everything is "content-addressed" can land as such of a big mic-drop moment when I've never heard the term or the concept in my life and the front page does absolutely nothing to explain it beyond that.
------
EDIT: My tone here is a little more antagonistic that I meant (proofread kids, don't just check for spelling and publish) but my first impression was a kind of "buzzword-y" vibe. I've looked a bit more and the authors seem genuinely passionate about shaking things up and trying something completely different, which I can respect. I'll leave it up as is because I still think my issue are legitimate, but the tone is a little off and I apologize.
------
Let's take my discovery path so far as an example:
> Functional language: cool cool. I know what that is. Immutable: also cool. Content-addressable: no clue. Saying it'll simplify code bases and eliminate dependency and "no builds" is supposed to sound amazing, but it really doesn't land when I have no clue what the premise is.
> Alright, that's it for the front page. No code examples, nothing linking the currently known to this new paradigm-shifting stuff. K. Let's try the docs.
> The Welcome is the state of the project without saying anything about the language itself. Roadmap isn't gonna help Quickstart! Let's look there.
This amount of effort for discovery isn't very helpful for me. I found a selection of talks elsewhere on the site. One of them is labeled "This is a longer (40 min) introduction to the core ideas of Unison and probably the best talk to start with." That might be a nice link for the front page.
I unfortunately don't have anymore time to look at this this morning, but the first 5 or so minutes of the talk say waaaaaaaaay more than the first however long I spent. Honestly, I think all of that information (code examples, linking core ideas to what we already know, basis of comparison) could be on the front page.
The tl:dr I can glean from it is:
It's kinda like Haskell, but every definition is turned into AST and put in a hash table. Any references are secretly references to the table, so changing a definition is making a new hash and changing the reference, and renaming is changing the reference to name table.
Also, everything is append instead of rewrite, which makes all kinds of stuff cleaner, like versioning and refactoring.
Pretty neat idea, I just don't really like how long it took me to come to that knowledge. I don't know how well it would scale or be usable in a real world scenario, but I also have never used Haskell or any functional language in a "real world" scenario so I'm not the best one to ask.
Definitely appreciate this honest and helpful, specific docs feedback, so thanks for taking the time to put it together. We do want the value of Unison to be straightforward given even a quick skim of the site, so: sorry about the current state, we'll try to improve it. :)
Just to add to that - I’m kind of in the same boat here. I had to read the homepage and intro sections a few times and I’m honestly still a bit lost in understanding who this benefits and why.
Just by way of anchoring: I’m no dunce, I’m a typical nerdy guy who knows his UNIX and has written lots of C, Python, JavaScipt, Ruby, etc. Written some mobile apps. Written plenty of web stuff. But I’m not immersed in any academic language study and not really an FP guy.
I don’t think you should dumb this down - the text itself is very good prose. But the context is missing something — perhaps a paragraph or two of anchoring for us “normal programmers” to explain why this is relevant to people who normally write Python web apps or Rust utilities or C++ games all day long (or if it’s not relevant, why, and who it is relevant for).
No worries. I guess it sounded a bit antagonistic, I apologize for that. I am actually interested in the idea, I was just a little frustrated that it was hard to figure out what was different about the language.
It's mainly just an issue of manpower on our end (we do accept doc contributions, but probably we should be doing it); having fresh reader eyes on it like this is still valuable though.
> It's mainly just an issue of manpower on our end (we do accept doc contributions, but probably we should be doing it); having fresh reader eyes on it like this is still valuable though.
That's absolutely fair, and tbh probably the problem. I've probably been thinking about the concept for so long that it doesn't occur to you that the phrase wasn't that well known.
I remember a multi-year project in college I was trying to explain about, and blew right through "potential energy surface" and lost him completely. I didn't realize it was something I'd have to explain.
content-addressable is admittedly perhaps a little bit niche. If you spend some time in the version control/distributed data structures space you will have run into it. But if you haven't d then you will perhaps never have encountered it. Your description of a hash table and references is a pretty close description of the idea at it's core.
------ EDIT: My tone here is a little more antagonistic that I meant (proofread kids, don't just check for spelling and publish) but my first impression was a kind of "buzzword-y" vibe. I've looked a bit more and the authors seem genuinely passionate about shaking things up and trying something completely different, which I can respect. I'll leave it up as is because I still think my issue are legitimate, but the tone is a little off and I apologize. ------
Let's take my discovery path so far as an example:
> Functional language: cool cool. I know what that is. Immutable: also cool. Content-addressable: no clue. Saying it'll simplify code bases and eliminate dependency and "no builds" is supposed to sound amazing, but it really doesn't land when I have no clue what the premise is.
> Alright, that's it for the front page. No code examples, nothing linking the currently known to this new paradigm-shifting stuff. K. Let's try the docs.
> The Welcome is the state of the project without saying anything about the language itself. Roadmap isn't gonna help Quickstart! Let's look there.
This amount of effort for discovery isn't very helpful for me. I found a selection of talks elsewhere on the site. One of them is labeled "This is a longer (40 min) introduction to the core ideas of Unison and probably the best talk to start with." That might be a nice link for the front page.
I unfortunately don't have anymore time to look at this this morning, but the first 5 or so minutes of the talk say waaaaaaaaay more than the first however long I spent. Honestly, I think all of that information (code examples, linking core ideas to what we already know, basis of comparison) could be on the front page.
The tl:dr I can glean from it is:
It's kinda like Haskell, but every definition is turned into AST and put in a hash table. Any references are secretly references to the table, so changing a definition is making a new hash and changing the reference, and renaming is changing the reference to name table.
Also, everything is append instead of rewrite, which makes all kinds of stuff cleaner, like versioning and refactoring.
Pretty neat idea, I just don't really like how long it took me to come to that knowledge. I don't know how well it would scale or be usable in a real world scenario, but I also have never used Haskell or any functional language in a "real world" scenario so I'm not the best one to ask.