It was mentioned already in other posts here, the documentation is quite cumbersome to read in places. Without going into specific details (sorry, I know that this is not too helpful) there is a tendency in the documentation that I have already noticed in previous releases, but which is very strong here: the descriptions seem to assume a lot of previous knowledge of the reader - not only about WordPress and website building in general, but about Pro specifically. For example, components are introduced and explained as an improvement on global blocks. While this is true, of course, I feel that this is inappropriate, especially for a new user. As if one had to learn about something old, that doesn’t even exist anymore, to understand a current feature.
This is the example that comes to my mind now, but it is not the only one. Overall, it feels a lot like reading an “insiders” document, that excludes or at least makes it very hard on even an experienced outsider.
Edit: I just read your comment in a different thread, @alexander, that the documentation is still mostly a collection of internal notes, so that would explain it 
But, as mentioned above, I also had the same feeling about the docs in previous releases.
Hi @striata,
Thanks for writing in about this. No worries on not having specifics, I know what you mean and see where you’re coming from. Regarding Global Blocks, I think we can make some adjustments there to help people know it’s not important unless they already have experience with the older model. I’m glad you found my comments on the other thread (for anyone starting from this thread, we’re talking about the conversation here: 5.0.2. Beta 1 - Initial feedback). What I was saying there mainly applies to the Parameters documentation. The rest of the articles are close to their final form, but we’re leaving room in case iterations from beta feedback would materially change them.
A couple thoughts on docs in general:
- Technical writing can get very long and exhausting to read if there are too many detours so in many cases we write from assumption of the reader having an understanding of WordPress and web technologies in general. We’d rather write shorter articles, and leave the reader responsible to fill in unknowns that are not directly part of our products. Our video training material and YouTube channels are where we go deeper on these things because the format is more conducive to presenting complex information.
- Arguably, most people don’t like to read the documentation. A better experience is that when you’re using a tool, you slowly try out one mechanic at a time, and your understanding of how things work together builds up slowly at a time. A simple example would be a first time user dragging in several different elements to see what’s available. Ideally, Documentation should serve as a source of truth so you know how everything is intended to work together. It should fill in smaller gaps in your understanding rather than being the driving source of information. I admit that in this case, we’re leaning heavily to the wrong side when it comes to Components and Parameters. There isn’t enough in the tool yet that lets you naturally explore those systems without advance knowledge. It’s definitely a gap we’re aware of but may not be fully closed until we have the visual parameter editor. By far it would be a better experience if your first encounter with Parameters was in a visual editor with immediate feedback vs an empty code editor. It would also be ideal if there were “starter templates” that predefined some component exports for you to use as a starting point.
Perhaps an idea such as allowing trusted users to add comments that would be reviewed to specific parts of the documentation would be a good way to allow certain parts of the documentation to become more accessible while not increasing the amount of work for the core team.
The following guidelines would need to be followed:
- The added comments would be either a full solution or tips & tricks (Meaning the added content would not leave the reader with more questions than they started with)
- They should only be added after being reviewed by the themeco team
There are some long time contributors to the community that would have a lot of insight to add or can provide more context on certain features because they actively develop with the theme for the end users.
I can see how that would be valuable, but I don’t think adding comments is the right vehicle here. It would take some work to curate it, and I imagine most of the comments would be people asking support questions based on the subject of the article they are reading. We used to have a peer-to-peer forum, which was intended to be somewhat of a vein for those interactions but it ended up being more questions than answers, most of which could be directed to our support team.
There are some long time contributors to the community that would have a lot of insight to add or can provide more context on certain features because they actively develop with the theme for the end users.
100% agree. I do think there’s plenty of shared experience that could serve newer users. I don’t think it’s something we want to focus on near term though. I get into it more on the other thread linked above, but we’re in this season of building as we go. The current Stacks are going to be relegated (always backwards compatible, but not front and center) in favor of a new set of options, and they will require a new onboarding process to help you make decisions on how to get started with a new site. When the Theme Options reboot is complete, I expect it will necessitate a rather large documentation refresh.