Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: introduce technical terms before using them #108

Open
achille-roussel opened this issue Mar 4, 2024 · 0 comments
Open

README: introduce technical terms before using them #108

achille-roussel opened this issue Mar 4, 2024 · 0 comments
Labels
documentation Improvements or additions to documentation

Comments

@achille-roussel
Copy link
Contributor

achille-roussel commented Mar 4, 2024

Throughout our README, we make use of advanced technical terms without defining them, which makes it difficult to appeal to a wide audience.

Here is a quote from some a piece of feedback we received that explains the problem:

I opened the GitHub, saw:

"Dispatch is a platform for developing reliable distributed systems"

and I liked it, got hooked on that.

Then I read that it provides "durable coroutines" and got a bit confused, not sure what that means, but I was thinking maybe it was explained later.

"scheduling of function calls across a fleet of service instances" sounds good, I imagine a bunch of remote machines executing what I need, not sure what Dispatch does, but the idea sounds appealing.

"fair scheduling" sounds cool, but I'm not really sure what it means.

"transparent retry of failed operations", sounds cool, although I'm not sure what "transparent" means here, but interesting.

"durability" I'm not sure what it means, because I think it's about execution and not storing data (as far as I understand), and then I'm not sure what's gonna be durable...

Then there's another term "Stateful Functions", and I'm not sure what that means. Not sure if it's the same as "durable execution semantics" and if that means that "if the function fails with a temporary error, it is automatically retried, even if the program is restarted, or if multiple instances are deployed", but I'm not sure if those concepts are independent or they refer to the same idea in that last phrase.

To address this issue, we should make sure that we always introduce technical terms before using them. Let's also be warry of definitions that rely on other technical terms; the aim is to explain complex concept in simple words so the product value can be communicated to a broad audience.

@Pryz Pryz added the documentation Improvements or additions to documentation label Mar 8, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
2 participants