[Discussion] Integrating Valkey GLIDE Documentation with Valkey doc site

[Aryex]

Hello everyone,

We'd like to open a discussion regarding the integration of the Valkey GLIDE client documentation into the official Valkey website. GLIDE is the unified client for Valkey, and as it is an official client, we would like its documentations to be easily accessible from the main Valkey website. Our primary goal with Glide’s documentations is to provide a user-first experience, complete with comprehensive guides, tutorials, references and a user-friendly UI. As such, we would like to discuss the best path for integrating our dedicated GLIDE documentations with http://valkey.io

Specifically, we'd appreciate guidance on the following points:

• Technical Integration: Our doc site will be statically generated. What are the recommendations for integrating with http://valkey.io/ ?

• Style Consistency: We would like to maintain a consistent visual style between our dedicated documentation site and the existing http://valkey.io/ design. Are there any existing style guides that we should use?

For reference, our WIP documentation can be found at https://github.com/valkey-io/valkey-glide-docs.

Thank you!

[madolson]

@zuiderkwast I know you have had had some opinions in the past along these lines?

[zuiderkwast]

Yeah, if we add glide docs, do we also want to add all the other official clients? If some are missing, then it looks as if they're not documented.

We could add them all to our website, but I'm not sure it's a good idea to put all content in a single doc repo. The doc repo becomes a monorepo. It makes it harder to maintain the docs as no single person has the overview of all our projects.

Could we generate the website from multiple repos, one for each client? We can also consider using some subdomains of our website for our different projects. I can imagine some client libraries want to use generated docs, like doxygen/javadoc, to create their docs, rather than requiring zola for all our docs.

I can already find some client docs here, that we could probably move to valkey.io subdomains if we want:

• https://valkey-py.readthedocs.io/en/latest/
• https://valkey-java.io/

Another approach (that seems to be preferred by distro maintainers) would be to include the docs in same repo as the code (for each of our code repos). Then, the docs becomes versioned together with the code. The only reason we don't do this for valkey core is that the docs are of a different license (creative commons share-alike) that we inherited from redis original docs. That doesn't have to be the case for new projects like GLIDE, so perhaps it's better to put the GLIDE docs together with the code and it can be updated in the same PRs as the code.

[Aryex]

@zuiderkwast Thanks for the inputs. I'm leaning towards subdomains as it allow greater flexibility on our part, but I'll discuss with the rest of the team on this.

Regarding styling consistency, Is it safe to say that we are ok with some differences (e.g. site fonts) as long as major branding elements stay the same (e.g. using the same Valkey Logo)?

[zuiderkwast]

Regarding styling consistency, Is it safe to say that we are ok with some differences (e.g. site fonts) as long as major branding elements stay the same (e.g. using the same Valkey Logo)?

I would say yes, but I'm a programmer. Programmers are known to be useless at design. 🤣

[stockholmux]

Generally, I think I'm more/less aligned with @zuiderkwast - keeping docs separated so we can scope expertise. I think I'd like us to focus on each client having a subdomain to keep a bright line between Valkey's documentation and the client's documentation (and between clients too), however I'd like a relatively cohesive common design language amongst official client libs. It should be clear it's part of Valkey, but also clear that you're on the client library's docs.

In the fullness of time, I'd love us to have some limited cross pollination of client documentation and project documentation. For example, it would be amazing to have a set of examples on command reference pages to see how you can use a particular command in multiple languages - then these could link to the client lib docs for further details, but mixing them beyond this seems a step too far.