Update readme - Githubissues

operating-function / pallas

An event sourced, purely functional application platform.

https://docs.opfn.co

Other

43 stars 0 forks source link

Update readme #9

Closed vcavallo closed 3 months ago

vcavallo commented 3 months ago

Here is the updated Readme for final review. Closes #7 Closes #6 Closes #4 Closes #1

vcavallo commented 3 months ago

@kjekac @cvanetten One thing I want to call out as maybe-odd: in the readme, we show a very terse version of the count-up cog (see screenshot below). One reason it's important to include this as a screenshot rather than markdown is to get syntax highlighting in the Readme. A necessary evil at this point. and we're not asking people to copy/paste this anyway.

But this PR proposes using a very verbosely-commented version of the same file (see files changed to review). The readme does mention that the actual source file has a lot more comments to peruse. Is this "conflict" too confusing? I think it's fair to have a screenshot in the readme with a very terse explanation and then a pointer to the actual file with more comments, but I can see it being confusing maybe.

cvanetten commented 3 months ago

I don't think it's confusing. It's not ideal to have a screenshot instead of a block of code, but we already discussed that trade off and I agree this is reasonable for now

kjekac commented 3 months ago

Reading this now, i think a major thing i would like to see as a reader is a brief overview of the architecture. As-is, we jump straight from "this is what this is on a high level" into "here's Sire".

"Okay, this is an event-sourced operating function, cool, i can kind of make sense of that if i think about it. I wonder what it consists of, does the design make sense?" "Here's how you write apps in it!"

We don't have to go deep into how we do IO, but just something like the tower diagram i showed at LC and maybe say something about

Sire bootstrapping itself from PLAN
Rex
(that the runtime acts as a kernel outside the system ("exokernel") which interprets calls to hardware completely opaquely, thus allowing the formal system state to be decoupled from any particular implementation).

Should i create a new issue for this? I think this PR is fine to merge as-is since it's a clear improvement.

kjekac commented 3 months ago

Btw i don't think this closes #1? You might want to check your list there.

vcavallo commented 3 months ago

Btw i don't think this closes #1? You might want to check your list there.

It does because I've uploaded the binary and added the link to it here. But I'm still testing the intel binary (long preamble on this old mac) so it's a bit presumptuous

vcavallo commented 3 months ago

Reading this now, i think a major thing i would like to see as a reader is a brief overview of the architecture. As-is, we jump straight from "this is what this is on a high level" into "here's Sire".

"Okay, this is an event-sourced operating function, cool, i can kind of make sense of that if i think about it. I wonder what it consists of, does the design make sense?" "Here's how you write apps in it!"

We don't have to go deep into how we do IO, but just something like the tower diagram i showed at LC and maybe say something about
* Sire bootstrapping itself from PLAN

* Rex

* (that the runtime acts as a kernel outside the system ("exokernel") which interprets calls to hardware completely opaquely, thus allowing the formal system state to be decoupled from any particular implementation).
Should i create a new issue for this? I think this PR is fine to merge as-is since it's a clear improvement.

plopping this updated tower diagram here for use later: