Conversation
|
""" WalkthroughThe README.md file was revised to reorder and update badges, move the Bluesky link to navigation, expand the "What's inside" section into three detailed subsections, clarify installation with a recommendation for the "uv" package manager, and elaborate on usage by introducing three subsystems. Contributing guidance was updated with a new status subsection, and additional external references were added. No code or API changes were made. Changes
Poem
""" 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (14)
README.md (14)
20-20: Navigation bar consistency: Relocating the "Bluesky" link into the main navigation ensures a cleaner badge section. Consider grouping external community links together or alphabetizing for easier maintenance.
32-35: Refine "Abstract" section description: The new "### Abstract" subsection is a clear split. However, consider tightening the first bullet for formality and clarity. For example:- A few tidbits of _structured docs_ along the idea of a basic and generic [hierarchical outline]. + Structured documentation based on a generic [hierarchical outline].
37-40: Clarify output generation description: The second bullet is informative but could be more concise. For example:- Utility programs that read outline files in [YAML] format and produce output files or packages by expanding all links, for example, into [Markdown] or [llms.txt] formats... + Utility programs to parse [YAML] outlines and generate outputs (e.g., [Markdown], `llms.txt`).
42-47: Punctuation consistency in Abstract bullets: The third bullet is well-detailed. To maintain uniform style, ensure all bullets either end with a period or none do.
48-48: Section heading clarity: The "### Applied" heading distinguishes use cases nicely. Consider renaming it to "### Applied Use Cases" to make its purpose more explicit.
50-66: Enhance parallelism and conciseness in Applied bullets: Some items can be tightened and follow a parallel structure. For instance:- The outline file [cratedb-outline.yaml] file indexes documents about what CrateDB is... + The `cratedb-outline.yaml` outline indexes documents about CrateDB. - Output files are produced to the [about/v1] folder. + Output files are generated in the [about/v1] folder.Also break longer bullets (e.g., the documentation subsystem one) into multiple points for readability.
69-69: Highlight the package manager name: To improve readability, formatuvas inline code. For example:- The authors recommend using the [uv] package manager. + The authors recommend using the `uv` package manager.
83-83: Terminology consistency: Instead of "The program provides three subsystems," consider "Thecratedb-abouttool provides three subsystems" to align with the CLI context.
85-87: Subsystem naming alignment: To mirror the CLI commands, you might rename "Query" to "Ask" or "Conversation", matchingcratedb-about ask. This improves discoverability.
175-176: Simplify contribution phrasing: The sentence can be more concise. For example:- Contributions of any kind are very much welcome and always appreciated. + Contributions are welcome and appreciated.
178-180: Clarify project status: The combined "planning/pre-alpha" may confuse readers. Suggest:- The software is in the planning/pre-alpha stage. + The software is in the pre-alpha (planning) stage.
188-188: Link label formatting: The reference label[hierarchical outline]is lowercase and spaced. Consider matching capitalization (e.g.,[Hierarchical Outline]) or using a concise label like[Outline]for consistency.
190-190: Alphabetical order of link definitions: The[Markdown]reference appears after[llms.txt]; consider sorting link definitions alphabetically to streamline maintenance.
192-192: Link reference consistency: If you formatuvas inline code in the body, ensure the[uv]link label here matches (e.g., use backticks in the reference label).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(5 hunks)
🔇 Additional comments (4)
README.md (4)
3-3: Badge ordering improvement: Moving the "Status" badge to the top emphasizes the project's maturity upfront, which is helpful for users scanning the README.
6-6: Prominent download metrics: Elevating the "Downloads per month" badge increases visibility of adoption metrics. This placement makes sense for prospective users evaluating project popularity.
193-193: Acronym link consistency: The[YAML]reference is uppercase, which aligns with common practice for acronyms. Good consistency with other acronym labels.
195-195: Reference housekeeping: The[Bluesky]link definition is now declared since it's used in the nav. Verify that you intend to keep the Bluesky entry in navigation—if not, remove this reference to avoid dangling links.
| | [License] | ||
| | [CrateDB] | ||
| | [Community Forum] | ||
| | [Bluesky] |
There was a problem hiding this comment.
I've tuned down the reference to Bluesky now. It currently points to https://bsky.app/search?q=cratedb, but the outcome isn't very pleasant.
The link should actually go to the CrateDB profile page https://bsky.app/profile/did:plc:kj3ndittnoqihvftw6rnn643, but that outcome would be even more unpleasant.
Request: Could the company finally ramp up its extrovert nature and start maintaining a proper presence on social networks where actual humans communicate and collaborate, optimally on both Bluesky and Mastodon, because Twitter is offically a thing of the past?
/cc @michaelkremmel
There was a problem hiding this comment.
If there is interest to improve relevant details, don't hesitate to ask how this can be made both efficient and fun. In this case, let's discuss on behalf of an out-of-band thread or conversation?
| ## FAQ | ||
|
|
||
| - Q: Seriously, how do I use this? | ||
|
|
||
| A: As mentioned above, this repository includes content and a few utilities | ||
| to manage corresponding information. Users will directly use the produced | ||
| [llms.txt] and [llms-full.txt] files. Developers will install the [cratedb-about] | ||
| package to access fundamental outline information in their own programs | ||
| programmatically, or to invoke fragments of the production machinery | ||
| on their premises, either ad hoc, or by including it in automated pipelines. |
There was a problem hiding this comment.
Users will directly use the produced llms.txt and llms-full.txt files.
I would like to elaborate a bit more about the "how".
While the context files are currently used by the built-in cratedb-about ask subcommand, that's actually just a workbench tool, so the files would like to see applications in actual end-user applications.
Can someone support us by providing relevant information how that would work with contemporary (desktop) applications, for example?
I don't know much about the state of the onion, but a quick search reveals the advent of those early movers in 2023/2024 already: Quora Poe, ChatGPT for Mac, Perplexity App, Claude Desktop.
There was a problem hiding this comment.
Additionally to that, let's also "use" them within a lightweight chatbot example application accompanied with this package, for example using Streamlit, or anything else that is viable to ramp up such an interface without much custom programming.
| - Q: It looks like the knowledge base machinery is missing important information | ||
| about CrateDB. I've asked it about matters of polymer sharding, and the answer | ||
| wasn't very insightful. | ||
|
|
||
| A: Well, we can understand your disappointment. To improve the situation, | ||
| we are constantly curating content, and you can support the process by giving | ||
| us hints about which fragments of information to include in the set of | ||
| curated information. To learn about what this means, see also [ABOUT-24]. |
There was a problem hiding this comment.
That paragraph has been added to evangelize the need for support about further content curation.
/cc @kneth, @michaelkremmel
About
The README was reasonably clear already, but it can always be improved. At some point, we may break out details into dedicated pages.