We’re excited to share that we’re kicking off a project to update our Docs! 
Our goals are to ensure the content is accurate, organized, consistent, and helpful. As a first step, we’ve been concentrating our efforts on a new format for the Layout doc, and once we’re happy with it, we plan to use it as a template to update our existing docs.
We’d be grateful for your feedback on:
- Is the structure and format of the doc easy to read? Is there anything you’d change?
- Is the content of the doc clear and easy to understand? Is there anything you’d add or change?
A couple of things we’re still working on:
- Adding screenshots of how an app renders with and without the use of the Layout component.
- Including a sample app that utilizes the Layout component.
Excited to take your feedback into consideration as we improve our docs! Thanks!
3 Likes
I think it’s great that you’re focusing attention on improving the documentation.
My first reaction is: run it by a graphic designer.
There’s obviously a lot of content there but it could be better organized and much better presented. Having a wall of text without much formatting in terms of color, etc. is not a good idea. And even the text… it’s repetitive and should be streamlined:
And this next screenshot makes me wonder why the screenshots are all different sizes. It doesn’t look good.
For a single document that stands as an example, I think this can be much better. A graphic designer will point out half a dozen things that could be improved.
1 Like
I also wonder about using tabs (Alignment, Layout, Image, etc.):
It might just be me but being a long-time Googler, I tend to skim web pages for information. My eyes almost never notice the tabs. So my assumption is that there isn’t that much information on the page. It obviously might be that I need to remind myself to check for tabs but I wonder if that’s the case for others. It might be better to have links to that information or to include all of the info on a longer document.
I’m not sure what the best answer is in this case…
I want to second what @tatiang said but also add that I personally like seeing the blocks with ACTUAL descriptions of what they do and maybe an example for more complex ones. For example the object blocks and an example of how to parse a return/json. Some of the info on blocks is also very vague. Remember, a lot of the users are beginners and detailed descriptions will help them work through issues easier and not have to rely on the forums as heavily which will boost confidence in ones abilities.
1 Like
Hi @tatiang,
First, thank you so much for taking the time to review the WIP template doc and share your feedback. I really appreciate and value your opinion.
I’ve bucketed my response based on the main concepts you flagged.
Graphic Designer
That’s a great suggestion, thanks. I’ll loop in our incredible Design team to review the docs as well. I anticipate we’ll be limited by the confines of our current docs platform, but perhaps they can suggest some workarounds to have our docs looking the best they can.
Table Organization
I agree that the tables could be more visually appealing. Unfortunately, there are limited customization options available with our current docs provider. We may be able to make some revisions through custom CSS, however. The team and I will investigate this and see if it’s worth the time it will take to implement changes. As for the repetitive text, this is excellent feedback. Thank you! The idea behind formatting it as we did was that a user could visit the table and get all the information they needed about a specific property setting from one row. But perhaps a better approach would be to pull the repetitive text out to streamline the table’s contents. Again, thanks for this suggestion; I’ll discuss it with the team.
Tabs
Nesting the property description tables in tabs wasn’t my first choice for the reasons you mentioned. I’d hoped to nest them with expandable sections, but unfortunately, that functionality isn’t available in our current platform. While I agree that it isn’t the best option, I think it’s the best option available to us at this time, as I’d prefer not to link back and forth, creating a confusing linking web. Perhaps I can add some additional instructions or investigate how to make the tabs stand out more on the page. I’ll dig deeper into this and continue to seek feedback from our Creators.
Different Size Screenshots
This bothers me too! I’ve tried countless approaches to remedy it. I met with the team at our docs platform vendor, and they’re stumped too. I have an open support ticket requesting assistance troubleshooting this, and they’ve escalated it to their secondary support team. Hopefully, it will be fixed soon! 
Again, thank you so much for your knowledgeable and valuable feedback, Tatian. We really appreciate it!
Lindsay
1 Like
Hi @samclever,
Thank you so much for taking time to review and provide feedback on this template doc. I really apprecaite it!
Yes, we’re working on adding examples of block combinations, so Creators can get a better understanding of the block in action! I agree that this is such a crucial element of the learning journey, especially for those who are new to app development.
Best,
Lindsay
2 Likes
