sm4rtm4art commented on issue #11388: URL: https://github.com/apache/datafusion/issues/11388#issuecomment-3410737313
### General thought Is there a recommended length for documentation pages? By “Do good and talk about it” (“Write cool software and tell people about it” – Paul Dix), I interpret “talk about it” as: catch interest quickly and then give readers a path toward deeper understanding—the why, the how, and also the how-not/what-not. Based on that, I’d suggest keeping the “user” description broader, general reference-rich and more leaning towrds SQL, and making the “library user guide” deeper and more relational, guiding readers toward docs.rs, leaning towards Rust. * User Guide: ~200–500 lines * Deep Dive: ~500–1000 lines (These are ballpark ranges, not hard limits.) ### Proposal based on the above 1. Should we keep two documents as mentioned? If yes, I would write “A Gentle Introduction to DataFrames” for the User Guide—covering general ideas, connectivity, and usage—and a “Library User Guide” that is a deeper dive into DataFrames. 2. This split might also address the second part of the issue by giving a path from the basic user context of DataFrames to how SessionContext fits in. 3. "Also, is it the case that I can only create a data frame via SessionContext? ": I would place this into the User quide. Do you agree with this concept, any suggestions, or am I on the wrong track? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
