Evolve "Features" and "Application Domains" sections

[amotl]

About

This patch intends to improve the actual usability of the non-reference documentation, in terms of guidance Matters of layout, shape, and structure. . It is mostly based on cross linking Linking to different locations of the documentation. , but also adds some new content New content being added. where there have been gaps on properly outlining features and use cases, and in particular, where the documentation failed to answer the question "What can be done with CrateDB?" properly and quickly.

The patch also tries to provide a clear information architecture to this realm of the documentation, i.e. concise categories where content should go, through the physical entities of folders, and correspondingly aligned logical entities of documentation sections, using a reasonable »naming things« approach. ¹

The improvements mostly focus on the "Features" and "Application Domains" sections, because the third one, "Integrations", already inherited its layout and shape from previous curations and improvements over at Drivers and Integrations, so it doesn't need to recieve so much love on this iteration, we will come to that later once more.

Preview

• https://cratedb-guide--53.org.readthedocs.build/feature/
• https://cratedb-guide--53.org.readthedocs.build/domain/

Thoughts

• It was clearly a failure to let engineers of other expertises manage the conveyance of relevant information details about the matters of feature and use case presentation on "the homepage". Up until now, despite receiving so many iterations over so many years, it does not manage to illustrate CrateDB's features and use cases concisely and thoroughly. This patch aims to remedy that.

• It was clearly a failure to separate the technical writing workbenches into "howtos" vs. "tutorials", as also elaborated elsewhere. Both terms/labels/categories are not tangible options to build an information architecture on. Previous refactoring patches already remedied this physically, this patch now concludes the improvement by evolving the semantic backbone into "features" vs. "application domains" vs. "integrations" instead.

• Contrary to what has been observed elsewhere, the jargon abstains from the typical LLM yapping seen on many other spots these days, by just not using it.

We will be happy to receive comments about other resources which would fit into those corresponding slots, like exercised here. We are sure we might be missing many valuable references, so please tell us about them, and don't forget to add any other suggestions which come to mind. As you've learned, it is all about improving cross linking Linking to different locations of the documentation. and guidance Matters of layout, shape, and structure. right now. Thank you! 💯

Details

The patch evolved from giving the "Time Series Data" section some love, then detoured into conceiving the "Industrial Data" section. After a few cycles, it became clear that a dedicated "Features" section was needed, and in fact, it was long overdue, because the CrateDB reference documentation does not provide corresponding guidance into how to use its features from a product perspective, mostly.

The previous title of this PR has been: Raw-Data Analytics, Industrial Data, and Time Series Data: Link to existing content. Improve guidance, structure, and layout.

About

A number of updates to bring in more content we already published on other platforms/systems, and to shape the sections about exactly three topics: data analytics, industrial data, and, orthogonal to that, time series data analysis. Those are mostly the main pillars of CrateDB's use cases up until now, with corresponding users.

More Details

General

• Raw-Data Analytics: Introduce use case where you need to retain all the records for running analytics on it.
• Industrial Data: Introduce real-world use cases. Improve appearance and layout.
• Document Store: Add reference to video tutorial about "CrateDB Objects".
• ML: Add section about "Exploratory data analysis (EDA)"

Time Series

• Expand canonical entry-point page about time series data
• Add dedicated sub-pages at the time series section
  • Time Series Basics
  • Advanced Time Series Analysis
  • Connectivity Options
  • Video Tutorials
• Use "time series" 2-gram everywhere

Preview

• https://cratedb-guide--53.org.readthedocs.build/domain/analytics/
• https://cratedb-guide--53.org.readthedocs.build/domain/industrial/
• https://cratedb-guide--53.org.readthedocs.build/domain/timeseries/

/cc @karynzv, @marijaselakovic, @msbt, @matkuliak, @wierdvanderhaar, @surister, @selina-meyer, @donmadeus, @hammerhead, @hlcianfagna, @simonprickett, @glagardere, @ThomasNpunkt, @widmogrod, @kneth

Footnotes

1. Naming things is important. Please provide feedback where you would like to see a different wording. Thank you. ↩

[amotl]

Conclusion

We hope you will appreciate corresponding improvements to the documentation, inrtending to embrace all features of CrateDB, and guiding readers to both the reference documentation and learning material (tutorials, guidelines) equally well, while adding a few more introductory words around it.

Acknowledgements

We would like to thank everyone who supported us by contributing code, by sharing ideas and suggestions, and by spotting bugs.

Of course, thanks to all for providing all the excellent material we are cross-linking to, and, last but not least, to all who are contributing to this excellent product, with special thanks to @dobe, @quodt, @burnes, @christianbader, @mfussenegger and @seut for starting it the other day.

Please let's not stop here, and continue to improve this "CrateDB Guide" section of the documentation, to make it a go-to place we can recommend to anyone, using concise pointers (URLs) to the relevant information.

Details

In order to conclude the patch, because we have been running out of steam, we had to sacrifice a few of the "feature" pages. Now, they have just quickly been populated to not ship them as empty stub pages. They definitively need a bit more love on future iterations. See also #53 (review).

• Backlog for "Features" section #101

Concluding this patch has been prioritized, because it is a dependency of another page we are intending to publish soon.

• Migration: Add page about Rockset #98 (comment)

We are intending to ship this together with improvements from another massive patch, which takes care about modernizing the documentation theme significantly.

• NG: Switch to modern responsive 3-column layout theme sphinx-basic-ng crate-docs-theme#390