Hi all - I've submitted a PR with a proposed rewrite of the
concepts/index.md doc in ratis-docs. I'd love to get feedback and
suggestions for it.
https://github.com/apache/ratis/pull/1338
For the time being, I've kept the content in a separate file, just to
make it easier to review and edit. My proposal would be to overwrite the
existing index.md and squashing commits before its finally merged (if
it's finally merged).
Thanks for your help -- Joel.
On 1/7/2026 5:32 PM, Joel Shepherd wrote:
Hi Xinyu - Let me try your suggestion about applying some GenAI. I've
been using it to help from a coding perspective with some success but
haven't actually directed it specifically towards synthesizing
documentation. I'll see how well it does if I give it that direction.
Thanks -- Joel.
On 1/6/2026 7:32 PM, Xinyu Tan wrote:
Hi, joel
Thank you for your interest. My suggestion is that you first go
through our existing documentation to see what’s available, and then
assess what documentation might be missing when you start using it.
Additionally, with the power of large models nowadays, I recommend
that you try using a cursor or Claude to have it analyze our Ratis
repository, which contains tens of thousands of lines of code (it can
fit within its context), and provide suggestions for new
documentation or even generate high-quality documentation. If you do
this, I can collaborate with you to improve the documentation.
Looking forward to your contribution!
Best
-------------
Xinyu Tan
On 2025/12/23 17:53:54 Joel Shepherd wrote:
Hi - I've been working with Ratis-3.x for the past few weeks. One
ongoing challenge I've run into is that while the code is reasonably
documented, there's plenty of information about Raft, and there are
some
easy-to-find examples, I struggle with having a broader
understanding of
how all the pieces are supposed to work together. A couple examples are
how client-side actions map to state machine invocations, how term
indexes should be handled to minimize the number of replays when a node
restarts, other events from the Raft layer that my state machine and
application should be prepared to handle, etc.
Outside of example code, does documentation like that (kind of a
conceptual or "programmer's guide" type documentation) exist? If it
does, I'd appreciate a pointer to it and apologize for not finding it
myself. If not, does the community think there would be value in
producing it?
Thanks -- Joel.
