Hello again from the 
team!
This thread is the first in a series asking specific questions about how you like your docs. We’re updating the UX/UI of our documentation pages this year and would love to get our community involved to ensure we get our redesign right.
If you have any general questions or comments, please head over to our announcement thread.
In this thread, we would love to discuss reference documentation: how and when you use it, what you need from it, and what makes the most organizational sense when you are searching through it.
What do we mean by reference documentation?
Reference documentation is specifically important for developers and technical editors who use CloudCannon. This documentation covers all the available configuration keys (e.g., _inputs) for customizing your CloudCannon experience.
An entry in the CloudCannon reference documentation would include:
- The key name
- The key definition
- Where and how you should use a key in your CloudCannon configuration file
- Links to relevant parent keys and subkeys
- Valid values for a key
- Real examples of how to use that key
A good example of the kind of content we want to maintain is the Collection Reference page.
Reference documentation is context-light, highly specific, and designed for developers or technical editors to use when they are customizing CloudCannon configuration. We imagine that you will use reference documentation the most when you already know what you are doing, but need a prompt:
- What was the name of that key again?
- Are there any other keys I can use to customize the appearance of my Collections?
- Can I change the value of this key from a boolean to a string to create a more specific configuration?
(If this doesn’t sound right to you, please reply to this thread. We want to know your perspective.)
Updating the reference documentation
At the moment, our reference documentation is hidden in our article navigation. That means it can be hard to find and is limited by the page layout of our normal articles.
In the 2025 Documentation Redesign, we want to give reference documentation its own home on the docs. The Reference section will be searchable, allowing you to jump straight to the key you need without wading through introductory articles on the topic. We also have the opportunity to update the layout of a Reference page, including how the reference pages are organized.
How would you prefer to search for configuration keys?
One of the main goals of the Documentation Redesign is to improve users’ ability to find what they are looking for. It is, therefore, important that we understand how our users expect their reference documentation to function.
We can approach the searchability of our reference docs in several different ways. Here are a couple of examples.
Example 1 – Organize keys by function
Configuration keys are sorted by function into “home pages” dedicated to a specific configuration topic. In this example, the reference section would function like an encyclopedia, with each page containing all the keys for a specific topic.
The reference section navigation would be an alphabetical list of these topic home pages, and the search bar would find the home page for the key you are looking for.
On the topic “home page”, lists of configuration keys could be alphabetical, hierarchical (i.e., parent keys first, then child keys), or further grouped by function (like the Text options subgroup on the Rich Text Editor page).
We use this model for our current reference pages (all Input configuration keys are together, all the Routing configuration keys are together, etc.).
Advantages of this model:
- Configuration keys are presented in-context, surrounded by other keys that are a part of the same function family.
Disadvantages:
- When you are looking for a specific key, you may have to scroll down the topic “home page” to find it.
Example 2 – Organize keys alphabetically
Configuration keys are sorted alphabetically, with each key having a dedicated page. In this example, the reference section would function like a dictionary, with each page containing all the information for a single key and linking out to other relevant keys.
The reference section navigation would be an alphabetical list of individual keys or perhaps a series of pages for all keys beginning with “A,” “B,” etc., and the search bar would find a page dedicated to a single configuration key.
We could use metadata tags to allow you to filter the reference section by function, showing all the keys for “Collections” or “Schemas”.
Advantages of this model:
- You find the exact key you are looking for quickly.
Disadvantages:
- If you don’t remember the name of the configuration key, you may have to search using terms found in the key definition.
- The navigation menu could be quite long.
Something else?
If these options don’t sound right to you, or you’ve seen an example of a documentation website that does reference better, please reply to this thread!
