Install consolidated Cloud Docs, and edit primary navigation section in left sidebar

[amotl]

About

This adjusts a few sections of the primary navigation component.

Details

• The CrateDB Cloud documentation has been refactored into the consolidated cloud-docs repository.
• While integrating it, move CrateDB Cloud menu item up ¹.
• Rename link label Install CrateDB to Self-Managed.
• Rename link label CrateDB to Getting started.
• Rename link label Reference to Reference Manual.
• Dissolve section C, listing individual drivers. This section has been reworked within the Clients, Drivers, and Tools section, and is much better presented now.
• Add two more links to bottom section D: Community, and Integration Tutorials.

Preview

https://crate-docs-theme--391.org.readthedocs.build/en/391/

Screenshots

A few iterations, from left to right.

Outlook

With GH-390, we will have another chance to overhaul the primary navigation section more thoroughly.

Footnotes

1. Under the hood, the cloud-docs repository will be linked into the documentation tree on behalf of a new project "CrateDB Services" instead of "CrateDB Cloud" (see services.py), in order to reflect it can be the home for more details beyond running a managed instance of CrateDB Database on cloud resources. This change is not reflected within the link labels yet, as it is only about plumbing right now, so that the new consolidated documentation repository is able to carry the weight of all future product ideas in this area. ↩

[proddata]

What is behind Examples and Stacks?

[proddata]

And why do we rename CrateDB back to How To Guides again?

[amotl]

Hi. The live preview is available at https://crate-docs-theme--391.org.readthedocs.build/en/391/.

What is behind Examples and Stacks?

It is a link to https://github.com/crate/cratedb-examples, which is more valuable than https://github.com/crate/crate-sample-apps.

And why do we rename CrateDB back to How To Guides again?

I proposed it, and we discussed it internally yesterday, so I thought it was acknowledged. Just using "CrateDB" is a bit poor, and does not convey what's behind.

[proddata]

I would like to understand some reasoning for the quite significant changes here, at least some sort of hypothesis why this improves the current situation. To me this menu looks very cluttered with lots of top level item like npgsql that are questionable to keep that way.

With the change from "How-Tos" to "CrateDB" the intention was to have one place to start using and understand CrateDB, separate from the technical description of the reference.

---

Having "Examples & Stacks", next to "Sample Applications" is confusing. What is used for what purpose? Also how is it different from Code examples in the community?

[amotl]

Hi Georg,

sure it looks cluttered, because it lacks structure and design, and the nesting is also wrong. This patch does not change much on the situation - there will be a bunch of others, also in downstream repositories, which aim to do that.

With GH-390, we will have another - and much better! - chance to overhaul the primary navigation section more thoroughly.

Other than this, the changes here do not have that much significance. If GH-336 would have been followed up upon, it might have made sense to rename the "Howtos" section, but currently it does not.

Top-level item like npgsql that are questionable.

Absolutely, you are not telling any news here. Improving this will be part of the refactoring love crate-clients-tools will receive, also partially based on modernizations from GH-378.

Having "Examples & Stacks", next to "Sample Applications" is confusing. What is used for what purpose?

In a future version, we may want to add tooltips, to better explain what's inside?

Also how is it different from Code examples in the community?

Probably not much, are you thinking about another canonical entry point to add here?

With kind regards,
Andreas.

[ckurze]

It is not as bad as you think, imho.

I would also avoid too many restructurings and "Examples and Stacks" is misleading right next to "Example Applications" (I personally found the example applications quite easy to use und well-structured in the repo, examples and stacks looks somehow cluttered).

Regarding naming, what about:

Installation Guide
CrateDB Concepts
CrateDB Reference
CrateDB Cloud
...

We should not link both repos "Examples and Stacks" and "Example Applications" - leaving as is and cleaning/merging the two repos sounds more appealing to me.

In the mid-term, the top-level drivers "JDBC", etc. should be moved under "Clients and Tools" (Maybe better "Drivers and Tools") - The current solutions makes users think that there are only four programming languages available, which is not true.

[amotl]

Hi.

1. I will back out bringing in "Examples and stacks", until it has received more love. Maybe only call it "Stacks"? /cc @matriv

2. CrateDB concepts is already elsewhere: https://crate.io/docs/crate/reference/en/latest/concepts/

3. Until https://crate.io/docs/crate/howtos/ may have received some inner restructuring, let's still call it CrateDB, meinetwegen.

4. The top-level drivers "JDBC", etc. should be moved under "Clients and Tools".

   Improving this will be part of the refactoring love crate-clients-tools will receive, also partially based on modernizations from Add modern components from the Sphinx ecosystem #378.

What about this variant?

• Install
• CrateDB
• CrateDB Reference
• CrateDB Cloud

At least, it would have a less cluttered visual appearance.

With kind regards,
Andreas.

Outlook

We should not link both repos "Examples and Stacks" and "Example Applications" - leaving as is and cleaning/merging the two repos sounds more appealing to me.

We should. And both should not be merged. »Examples and stacks« is a support repository for https://crate.io/docs/crate/howtos/en/latest/reference-architectures/, which never lifted off properly. All that scope will need a more thorough refurbishment. I see that we are not there yet, and that the downstream repositories will need more love.

[amotl]

That's an updated screenshot, based on the current state of the patch. I think it is an improvement (right) compared to the previous version (left), mostly on the overall appearance, and giving it a slightly better structure, at least.
-- https://crate-docs-theme--391.org.readthedocs.build/en/391/

[amotl]

If you think we should remove the "client drivers" section right away, by folding it into "Clients and tools", please raise your voice. Otherwise, I would postpone it to GH-390. Currently, it is a bit difficult, because the documentation assembly is lacking some features to be able to layout the menu more freely.

[proddata]

Regarding the custom CrateDB drivers. I think we need to be careful here. Just moving them into client and tools won't solve the issue that at least two of them are considered "legacy" and probably should not be used with modern CrateDB versions to begin with.

I would even argue moving the docs for them out of rtd altogether and just have it in the repo. We still could have examples in the "CrateDB" section.

[amotl]

Regarding the custom CrateDB drivers. I think we need to be careful here. Just moving them into client and tools won't solve the issue that at least two of them are considered "legacy" and probably should not be used with modern CrateDB versions to begin with.

We will have many more options when moving them out of the primary navigation, and into the crate-clients-tools repository instead, so we can have the discussion what to exactly do about those details over there later. We should not be too much concerned about it right now.

[amotl]

Hi again,

this is my next proposal based on our recent discussions, for the »Section A« of the left sidebar navigation.

With kind regards,
Andreas.

P.S.: While it may not be optimal yet, it changes the wording a bit, and opens up further perspectives. For followup development work on a more serious restructuring of the primary navigation section, I created https://github.com/crate/roadmap/issues/32, in order to collect more feedback internally.

[ckurze]

LGTM

Minor change I'd propose is to use capital letters as these are "headlines":

CrateDB Cloud
Getting Started
Self-Managed
Reference Manual

[amotl]

Also taking all the improvements from crate/crate-clients-tools#33 into consideration, this is a new proposal, completely dissolving section C, which listed individual drivers.

[amotl]

I am thinking about renaming the link label »Clients, Drivers, and Tools« to »Drivers and Integrations«, as a final stroke for this iteration.

[amotl]

This post has been diverted to crate/cloud-docs#18. Please follow-up over there.

---

About

• crate-docs-theme==0.29.0dev1 has been released, in order to be able to verify the new appearance on other projects.
• The preview can be inspected on the recently reworked CrateDB Cloud Docs project at https://crate-cloud--16.org.readthedocs.build/en/16/.
• Navigation works well.

Details

On the preview page, and in this screenshot, you will see both toctree variants currently defined at cloud-docs:/docs/index.md.

The bottom section reflects the previous physical structure "Reference vs. Tutorials vs. How-To Guides", and the top section is made of a handcrafted toctree, which is reflecting the same structure and the order of the items from the "Manage" section of that page, directly referencing corresponding sections of the documentation, no matter where they are located.

Q&A

On this matter, I am asking which variant you would prefer? I think the handcrafted version has a point, while the other one, based on the previous physical structure, will be dissolved anyway in the course of the next iterations? Let me know if you have a different opinion, or other suggestions about this layout/design/structure/UX detail.

/cc @kojinkai, @SStorm, @matkuliak, @msbt