More general feedback on docs.
The more that I use the platform, the more I realize that my initial impression was mistaken. As a new (technical) user, I’ve had difficulty getting a firm grasp of what the platform can do, partly because some of the best info is obscured by the documentation structure.
Here’s the top-level headings from Drag and drop page builder and CMS - Builder.io
General
Builder visual editor
Builder for Shopify
Tutorials
Developer docs
Account
My observations and suggestions:
- Having a heading called “General” is too general. The first heading should be something like “Introduction” or “Welcome to Builder.” Also, it shouldn’t be a section heading, it should be a single page that explains what Builder is.
- Case in point, the subheadings under “General” don’t speak to the idea of “here’s where you go to get a sense of what this thing that you’re looking at is.” The subheadings are: “How Builder works,” “Best practices,” “Builder technical overview,” and “Roles and permissions.” Each of these concepts–just going on the headings, not the content–is introduced too early. I don’t need to know how Builder works, what best practices are, a technical overview, and definitely not roles/permissions when I’m just trying to understand what is Builder.
- Shopify seems to be prioritized in a number of places (“Builder for Shopify” heading, “Tutorials–>Shopify” subheading). I get it, I’m guessing that’s a large part of your target market, but the current implementation in the docs makes it harder to find info for anything other than Shopify.
- There’s a kind of categorical confusion going on between some of the top-level headings and the subheadings. For example, “Builder visual editor” and “Developer docs” both have the subheading “Guides”–fine. But then why is there a top-level heading called “Tutorials”? Tutorials are similar to guides, so they should be at the same level. Either create a tutorial subsection alongside each guide subsection for every top-level heading, or merge all tutorials into a single top-level heading and merge all guides into a single top-level heading. As it stands, I don’t know what I’ll find under the top-level “Tutorials” section–is it going to be for the visual editor? Dev docs? Something else?
- Same thing goes for all the subsection headings that refer to specific platforms, for example “Developer docs–>Angular.” Is this going to be a guide to using Builder with Angular? If so, why is it at the same level as “Guides” instead of nested under “Guides”?
- Subsection headings that open up to reveal more deeply nested points need to have an arrow or some visual indicator that the subsection heading is a branch, not a leaf. It’s not clear at first-glance that “Developer docs–>React,” for instance, is actually a folder rather than a document. You can see the arrow when you hover over the link but it should always be visible.
- Nit pick: there are some folders that only have one document, e.g. “Developer docs–>Angular.” These should be just leaf nodes.
If I were redoing the docs, I would do something like this:
- Split off developer docs into a separate sub-site, there’s just too much stuff to cover.
- Restructure top-level headings on main docs like so:
- Introduction
- Quick start
- Creating content with the visual editor
- Integrating with external platforms
- Managing your account
- Dev docs site should be something like:
- Introduction
- Quick start
- Important concepts
- Guides
- Tutorials
- API reference
- Dev docs site should make workflows clear early on. There needs to be a clear transition from the general positioning of your product as a no-code tool to low-code tool. That Builder has three main use cases that can be mixed and matched:
- Building sites only in the visual editor without any coding
- Building sites in the visual editor with code components that you’ve written (requires integration with your codebase)
- Building sites in your own code with sections that you’ve created in Builder (requires integration with your codebase)
Just my $0.02.