-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: find a better place for "Extending LoopBack 4" in the sidebar [SPIKE] #5785
Comments
|
I would prefer to minimize the number of clicks to access important pages. To my experience, more levels of nesting makes it even more difficult to see sub-titles as the site cannot automatically unfold sidebar items. On the technical side, there are some pages that need to be read for both application and extension developers. |
I understand your concern. I figure out a way to show the drop-down items for "Building LoopBack 4 Application" and "Extending LoopBack 4" by default. When page loads, it looks like this: And no matter how you click the subitems, that two ul always stay expanded. Would you accept this nested way? It won't hide the sub-items, they always display. The trick is setting those two items as active(therefore expanded) all the time Change it to if pageurl.last == item.url or item.title == 'Building LoopBack 4 Application' or item.title == 'Extending LoopBack 4 in this line
Yes I agree, and the 2nd point in my proposal covers it I think. Or do you have more suggestions regarding the shared content? |
+1. Prefer not to have extra level to wrap the "building LoopBack application", regardless we find a way to expand certain sidebar items by default. For "extending LoopBack 4", i assume the original sidebar items are kept unchanged and we're just adding tutorials in it? |
The story is created from discussion
I was suggesting put "Extending LB 4" before "Reference guides", and Miroslav explained the reference is for app developers, so it should be organized with other app sections. My concern is, when listing all the top level sections in parallel like what we have now, it's even hard for me to understand that LB has 2 target users: app and extension. The four-quadrant documentation layout is also not clear, because introduction+app sections+extension section+reference+development all mix together. And I am afraid newbies won't get it unless we clearly separate app related sections and extension related sections. If the always displayed sub sections is too nested, how about using separators?
|
I should've elaborated my question. There are other pages, e.g. creating components, testing your extension, but i didn't see it in your mockup. So I was wondering if it's going to stay unchanged or move to other sections. |
@dhmlau Oh those extension tutorials will be moved to "EXTENDING LOOPBACK 4/TUTORIALS" I added a note for the menu in #5785 (comment) |
Agreed. How do we handle this? Maybe move the description aspect from Extending LoopBack 4 section pages to Concepts. Some concept pages already exists, in that case info from Extending LoopBack 4 could be used to augment it. If no corresponding concept page exists, create one. |
If we can keep the two items always expanded, then I quite like the proposal shown on Janny's screenshot: I would add "How-to guides", "Concepts" and "Best-practices" to "Extending LoopBack 4" too.
I am concerned about maintainability of this solution. If we change a section title in the future, or want to add another always-expanded section in the future, then we will need to make changes both inside As I understand sidebar entries, they are essentially a key-value maps. A typical entry has
I think we also need to pick a different CSS class than
This is a tough problem. On one hand, we want to make it clear that the same information is applicable to both application and extension developers, so that app developers can bring their knowledge to building extensions, and also to avoid duplication of content. On the other hand, we also want the content to be easy to discover. As an extension developer looking of a piece of information, I would like to find it in the documentation area dedicated to extension developers, otherwise I would never know where to look for what (whether in app area or extension area). What types of pages are most likely to be shared by both app and extension developers? We have "Tutorials", "Explanations", "How-to guides" and "Reference".
I am not sure about "Best practices", they don't follow cleanly into a single pillar. I think most best practices are going to apply to both applications and extensions, in which case it's probably best to have treat them as shared? Based on my thinking above, I am proposing the following structure for further discussion:
|
I propose some minor changes on top of @bajtos 's outline:
|
cc @hacksparrow the existing contents under https://loopback.io/doc/en/lb4/Extending-LoopBack-4.html are mostly how-to guide, with very few concept and tutorial. But since team has this concern, we can revisit them(2nd step) after having the right layout(1st step).
cc @raymondfeng yep.
cc @bajtos The 3 items under "Best Practices" are not related to extensions, we can add the sidebar when creating those content for extensions in the future. "Concepts" are shared, so I also tend to keep it separate as you and Raymond illustrated.
cc @bajtos My solution is very hacky, it mostly shows where to customize the sidebar items, and won't be the final solution. metadata like One thing I need to correct is, most of the extension contents belong to HOW-TO GUIDES, not tutorials. |
A summary of content refactoring:
The new content should look like: EXTENDING LOOPBACK 4/HOW-TO GUIDES
EXTENDING LOOPBACK 4/TUTORIALS
CONCEPTS
|
A summary of the new sidebar:
Implementation tips:
|
This is a follow-up to #5718, see also #5549.
Quoting from #5718 (comment)
Let's find a better way how to structure our documentation for application developers vs. extension developers.
Acceptance criteria
Propose a new organization of the sidebar and/or the doc website (we can e.g. move docs for extension authors to its own area/sidebar, as we have for LB2, LB3, contrib docs, etc.) Discuss the proposal with the team, reach consensus about the direction we want to take.
If the proposed version requires little effort, then open a pull request to make it happen. If it's more involved, then create well-defined follow-up stories.
The text was updated successfully, but these errors were encountered: