Docs Improvements Round 2 (started 2024-08-21)

[cvanetten]

README

• [x] Better demo that shows off the main system features
• [x] Add motivation for the project. What problem is it trying to solve and what is our approach?
• [x] Bang the “every operation is ACID” drum more
• [x] Further specify the status of incomplete work (caveats) or add a feature roadmap that describes future work
• [x] Update the code sample. The syscall is concerning without a more thorough explanation. The syntax is confusing too
• [x] “Regularity” and “homoiconicity” and not well known terms; update them to something more understandable
• [x] Move the link to the Plunder repo to the end of the document
• [x] Don’t use the term “operating system” right now. We can use OF and “application platform” (then the OF is a particular application on the platform). People erroneously think this is some kind of desktop replacement
• [x] “Sire” is used without introduction in the README
• [x] Clarify the difference between devenv and binaries. Binaries require the source files too
• [x] Clarify that binaries are just offered for convenience and do not need to be relied upon.
• [x] Improve the Quick Start so that people know you also need the source files (and why)
• [x] README code examples need a much more thorough explanation, either with comments or discussion
• [x] Reduce the amount of text in the README introduction, or better format it for ease of scanning
• [x] Move installation and quick start instructions to the bottom of the readme
• [x] After installation, users should stack run pallas instead of just pallas; update docs
• [x] Clean up the links in the README, documentation, and website
• [x] Adjust the size of the logos (Pallas and Org)
• [ ] Update image host to ensure resolution; GH content sometimes doesn't resolve
• [x] Dark mode images

Documentation site

• [ ] Add “event source” style diagrams to explain system architecture (use two machine communication example?)
  • [x] hand-drawn single-machine system architecture (runtime, VM, event log, host file system, etc.)
• [ ] Update LC/supercombinator/how we’ll persist partially applied functions. Land the “Hook”
  • [ ] Better explanation of how we go from event-sourcing -> “DB engine just by writing functions”
• [ ] Explain cog cache / booting (“why can’t I just change the Sire file? Why do i have to delete the ship?”)
• [ ] IO interface, hardware, and syscalls need much more explanation
• [ ] Elaborate on how system calls can be part of state
• [x] Further specify the status of incomplete work (caveats) or add a feature roadmap that describes future work
• [x] Don’t use the term “operating system” right now. We can use OF and “application platform” (then the OF is a particular application on the platform). People erroneously think this is some kind of desktop replacement
• [ ] More thorough documentation around cogs (databases). Be prepared for database guys to ask questions (cluster? consensus?).
• [ ] How can we do parallel computation while also promising determinism? This needs to be explained
• [ ] More information about metaprogramming capabilities, in particular how hot reload interacts with the event loop
• [x] Update the Introduction pages in gitbook. Make "Pallas" a more thorough discussion of the architecture.
• [ ] Architecture: could direct use of callbacks in a higher level language lead to callback hell? Prefer yield instead?
• [x] Remove the word “crash”; explain what happens if you have a type error (or an assertion fails) syscall is a scary word; if these don’t need to be renamed, we at least need to immediately explain what they mean
• [ ] The documentation needs to address namespaces
• [x] Build full reference documentation for core language features. Semantics, plus a small example of using it. In order:
  • [x] Atomic data types
  • [x] Data types
  • [x] Symbols
  • [x] Binding and all the binding forms (functions, recursion)
  • [x] Control flow
• [x] =?= needs more complete documentation. It is only used for unit tests and cannot be used in a function
• [ ] Add material about the current state of error handling and recovery. What happens if I do something bad to my database? What happens if I get stuck replaying an event that caused it to crash?
• [x] Remove references to “noun”
• [ ] Explain current state of type system and the various unsafe things you can (and should not) do
• [x] Make references to sire files hyperlinks, instead of just text
• [ ] Better explain how to read function application (with |); people will have expectations because of Unix pipes
• [ ] Describe large missing system pieces: interprocess communication, networking, content addressing, identity
• [ ] Sire cheatsheet
• [ ] Explain the * rune
• [ ] Explanation of why serializing lambdas is powerful; what workarounds do people currently use
• [ ] Create an overview of the language design, including things like basics of Rex, runes, why it looks like this, purpose, etc. This should be an Explanation that comes before Reference or Tutorials
• [ ] In the Documentation, remove linear references to prior pages; each documentation page should be independently readable (no, “as previously mentioned”)
• [ ] Clarify the end-developer use cases for adopting this technology
  • [ ] “I can write a full web app backend without ever having to deal with a database would be a very good sales pitch actually”
  • [ ] No devops
  • [ ] Networking
• [ ] Describe the functionality of trk; literally everyone asked about it
• [ ] Imports are not explained in the docs clearly; importance and point of load order is not clear; imports should be introduced before they are encountered, or explained with sufficient detail that they aren’t confusing
• [ ] Update website with OPFN brand name

[kjekac]

This looks very good! A few comments and thoughts:

“Regularity” and “homoiconicity” and not well known terms; update them to something more understandable

We need to talk about the value of Rex or just drop this. Only hardcore lispers care about these properties in the abstract. The value of Rex is the same as that of S-expressions: the syntax is decoupled from the language and so can be reused again and again. It's the whole "you want generic components that can be reused, since you can't afford to throw extra labor at specialized components".

After installation, users should stack run pallas instead of just pallas; update docs

(Or first do stack build pallas && stack install pallas, though i suppose that's a bit intrusive.)

How can we do parallel computation while also promising determinism? This needs to be explained

We don't, we promise deterministic replay.

Remove the word “crash”; explain what happens if you have a type error (or an assertion fails)

"Crash" as used in these places is really more aptly named "compilation failure". It's a simple concept that basically all programmers are familiar with. "Crash" should be reserved for runtime crashes, and we should maybe mention that you should never do this, though probably not in the same place as we discuss compilation failures.

Add material about the current state of error handling and recovery. What happens if I do something bad to my database? What happens if I get stuck replaying an event that caused it to crash?

First, see the previous note. If a cog crashes while processing an event, that's fatal. It will not continue to receive events, so there's nothing to replay.

[cvanetten]

I'm calling the initial Reference material done for now. We have:

• Bits
• Nats
• Cmp
• Str
• Rows
• Lists
• Either
• Maybe
• Sets
• Tabs
• Pads
• Bars
• Types

My next step will be adding type and function signatures to all of the existing references. After that I think there's probably two primary tracks:

• Add advanced concepts like: macros, rex and sire expressions, seed, etc.
• Improving the structure of the reference pages (for a worthy example, see Erlang

[cvanetten]

• [ ] Add a page that describes the functions of each rune