Call for feedback on documentation

Beta
#1

From the most recent status report:

Finally, we’d love to hear your thoughts on docs. Specifically, do you prefer more written articles or video tutorials?

Within videos, do you prefer bite sized or longer form? Say a topic is particularly complex — would you rather see one long video with section breakouts or several shorter ones?

We know that there is a time and a place for both the written word and video, but we’d love to hear your different perspectives as we’re putting together docs for this next cycle and thinking more broadly around documentation as a whole.

Thanks for asking :slight_smile:

I really like the in-depth videos you’ve made that dive a little deeper into certain elements and features. They’re very useful so please always keep making those. And @kory, you have a good voice and style for the videos which make them that more pleasant to watch/listen to :+1:

Shorter videos would certainly be nice too depending on the context. They could demonstrate how to do a specific thing in a video that is maybe only a couple of minutes long. Some of them may not even need any narration.

Written documentation is super important as you may not always want to scrub through or watch an entire video to get the information you need. It’s also easier to bookmark and perform quick search actions on the docs text to find what you need.

1 Like
#2

Thank you for jumping in on this, @JvP…great stuff! I appreciate your kind words on the videos and am glad that they strike a good tone with you. I have experimented with the idea of shorts that we could hopefully use to demonstrate a topic very quickly with little to no narration, so that’s interesting you’ve mentioned that. And definitely agree that written documentation has it’s place, and is especially helpful when sharing snippets or starting points with things that are more complex, especially features like Components and Parameters. Again, all good stuff, and thank you for your feedback!

#3

No problem!

Those shorts would be great placed inline in the docs.

I have some suggestions for the docs section as well if you don’t mind.

  • It would be handy to have the table of contents of an article sticky as you scroll down. That way you can get around a docs article even quicker
  • The index on the left does not always expand its top-level items to reveal where you are (after using the search bar anyway) Would be nice if it did
  • Have the article headline IDs appended to the URL for easy sharing and bookmarking of specific sections
2 Likes
#4

I previously commented on the Facebook post.

My preference is docs with shorter videos to reinforce the docs or show a concept.

Long videos are just time wasters for me unless it is something interesting like the Google sheets video. In those instances the videos definitely require additional docs with code samples. Docs are great as I can skim read, get to what I want quickly and move on.

Just an opinion based my experience. I purchased both the sliders and grid videos (and they were well done) BUT I have not managed to get through them. While they are informative there isn’t really a way to skip to what you need and it is impossible to know what you’ve missed so when I try to skim through them it usually means wasting more time trying to go back to what I missed.

1 Like
#5

Thanks! @urchindesign specifically…in the longer videos, do the chapters that we put up on YouTube help? The ones created by timestamps in the description that segment out the video scrubber / add little chapter cards on the mobile app? I always felt like those were nicer because I just had one video to go find and then when broken down, it’s like jumping to a “shorter” video within the larger context, and at least you can jump around if needed vs having to leave the video, go find another one, jump into it, et cetera.

Just curious your thoughts on that.

#6

I’ve never really been a video person. Perhaps I am too impatient. They do help but I still prefer a combo of videos and good docs.

The only time I watch video is if I want to check how to take something apart.

That said my favourite video is still the Google Sheets one, which is pretty long, but i still wish it had documentation / instructions and code to accompany the video.

1 Like
#7

Gotcha, thanks!

#8

I’d say a mix of both but with a slight swing towards video. Very much a visual learner. Chapters on youtube help loads when you want to get to a particular point…

2 Likes
#9

Thank you, sir!

#10

One last thing regarding docs.

Over the years Alex has always shared little gems in the beta forums, which if missed, are no where to be found. These were usually things that enabled people to extend what is possible. There are many I’m sure I missed and others that were shared in threads I was a part of.

It would great if these types of things were found in the docs.

One example was the ability to create our own custom conditions. This isn’t in any doc and unless you were part of the beta thread it was shared it, it is something many people would have no idea about. (if it is in the docs then please accept my apology but there are other examples.)

add_filter('cs_dynamic_content_condition', function( $result, $field, $args ){

if ($field === 'is-product-tag') {
  return is_product_tag() ? 'true' : 'false';
}

return $result;

},10, 3);

Perhaps there can be a space in the docs that contains snippets of what has been shared, whether common UI CSS overrides or PHP snippets like the above. This would be super helpful to me and I’m sure to many.

1 Like
#11

100% would love to see a collection of all the gems and extension snippets available.

I would include in this a more thorough detailing of what can be accessed via shortcuts, and some more about what the Dev tools allow / give you access to.

#12

Hey guys, thank-you for all the feedback. With regards to the beta forum, it has always been private and only viewable to those in the beta group however in the coming weeks, it will be viewable to the public and should start showing up in search results.

As part of this, we would certainly value which gems and nuggets are your favorite, and we could even potentially add those to the docs as well. If you have any specific suggestions or code snippets or posts/resources that are particularly helpful to you, please let us know and we’ll do our best to bring more visibility to them.

1 Like
#13

Well, this is certainly unexpected but very welcome news. Had a heated discussion on Facebook Messenger a few weeks back with someone on your team about the beta being closed so good to see the forum is being made public at least.

#14

The more beta testers the better

#15

Hey @dlukefinch

The beta forum will only be viewable to the public. You will still need to be active in support to be able to post. To date, we have hidden the beta from being indexed completely and the only way to see it is if you are logged into your account and in the beta group. Once we make the change, it will be public just like the rest of the forum is public, so others can find/view the content here.

In the meantime, if/when anyone has suggestions for articles or posts you’d like to see added to docs let us know. Otherwise, everything here in beta will soon start to show up in the search results (most likely around the first of the year).

#16

For anyone also looking to add more shortcut access, I have just noticed that in the inspector window, floating windows have a data-tco-shortcut which tells you what the shortcut code for that window or dialogue box is. Pretty handy, if you haven’t seen this already!

image
image1164×268 129 KB

1 Like