Documentation Organization Suggestions

[adriangalilea]

Hello guys, I tried getting into textual a couple of times now,

I completely love the project, but I wanted to give you some feedback from an outsider/noob perspective.

This is the Textual website, You have:

1. Home
2. Introduction
3. Tutorial
4. Guide
5. Widgets
6. Reference
7. API
8. How To
9. FAQ
10. Roadmap
11. Blog

Let's focus on these:

• Introduction
• Tutorial
• Guide
• How to

I know it may make sense to you, but, from the first moment I am already lost.

Suggestion: Please, put the introduction as the first section on the tutorial. Or the Tutorial inside the introduction.

Let's continue clicks Guide

Welcome to the Textual Guide! An in-depth reference on how to build apps with Textual.
Wait... Isn't there a Reference Link also? If the Guide is an in-depth reference, what the hell is in Reference?
Goes into reference
Sees Widget as a link
Wait... what is in Widgets then???
Goes to Widgets
This looks like something that could be inside Reference, not it's own section

Suggestion: Put Widgets and API inside References
Suggestion: Put What is inside how-to inside Introduction/tutrial too in a section called tips&tricks or whatever.

I wish I had more time(already running late to write this)

I can take more time if you need it to give proper feedback another day... I'll leave it here for now.

I also found many inconsistencies, and I really think it's due the issues mentioned above, you have so many sections where should be one, leads to inconsistencies and is harder to maintain.

Given this, thank you for all the work, hope I can get more time to look into cool things to build with Textual :)

Have a nice weekend.

Adrian.

[willmcgugan]

Adrian, we recommend you read the docs from left to right, like a book. Follow the "next" links at the bottom of each page. Care has been taking to introduce concepts in the order that you will need them.

[adriangalilea]

Hello,

I see what the intention was, but nav bars are not sequential conceptually, just different isolated sections, so having 5 nav bar links that convey the same leads you to not know where to go because you don't assume sequential, a table of contents would be sequential.

I don't mean to nit pick, I do a lot of UX design and since I like this project I wanted to give my 2 cents, but you are of course free to ignore or disagree with me. I can re-arrange it myself in a pr if that's somewhere available and you judge if you like it better or not 😄

I suggest you to ask someone who has no idea about the project where would they go in a hurry to get started. I bet you they will be confused about it too.

If you put the tutorial, introduction, guide and how-to under the same conceptual category it will become much more intuitive, they can simply be subsections of it.

Same if you place widgets and API on reference. Makes no sense to have widgets both under widgets and again on reference. Because it makes you doubt where from both options you should look.

I think the UX in that sense can be easily improved, but it was just my unsolicited advice, others might differ, if you want me to make this into a more elaborate UX design considerations let me know and I shall do that.