Hi Joel, Thanks a lot for submitting a pull request! I am reviewing it
Tsz-Wo On Fri, Jan 23, 2026 at 11:34 AM Joel Shepherd <[email protected]> wrote: > 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. > >>> > >>> > >>> > >>> >
