Skip to content
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

Closed
bajtos opened this issue Jun 19, 2020 · 14 comments
Closed
Assignees
Milestone

Comments

@bajtos
Copy link
Member

bajtos commented Jun 19, 2020

This is a follow-up to #5718, see also #5549.

Quoting from #5718 (comment)

As I see it, the first sections (up to "Reference guides") are for application developers.

The section "Extending LoopBack 4" is for people building extensions, that's why I prefer to keep it a kind of "outside" for docs for app developers. I think we should find new place for this documentation in the future, I'll open a follow-up issue to discuss this further.

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.

@bajtos bajtos changed the title [Docs] Find a better place for "Extending LoopBack 4" in the sidebar [SPIKE] docs: find a better place for "Extending LoopBack 4" in the sidebar [SPIKE] Jun 19, 2020
@dhmlau dhmlau added this to the Sept 2020 milestone Aug 7, 2020
@jannyHou jannyHou self-assigned this Sep 21, 2020
@jannyHou
Copy link
Contributor

jannyHou commented Sep 23, 2020

  • Most of the docs under "Tutorials", "How to guide" and "Concepts" belong to app developers, which simplifies this task a lot.
  • Tutorials/Build large scale Node.js projects with LoopBack 4 should be a series of tutorials shared by both app and extension developers. So I would suggest either refer to it at the beginning of "Extending LoopBack 4", or duplicate it under "Extending LoopBack 4".
  • The current layout doesn't distinguish the app development and extension development clearly. So I propose moving "How to guide", "Concepts", "Tutorials", "Best Practice" under a new section "Building Application"

The new sidebar would be:
Screen Shot 2020-09-23 at 11 19 05 AM

And unfold it:
Screen Shot 2020-09-23 at 11 19 17 AM

@raymondfeng
Copy link
Contributor

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.

@jannyHou
Copy link
Contributor

@raymondfeng

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.

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:

Screen Shot 2020-09-23 at 3 52 48 PM

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

On the technical side, there are some pages that need to be read for both application and extension developers.

Yes I agree, and the 2nd point in my proposal covers it I think. Or do you have more suggestions regarding the shared content?

@dhmlau
Copy link
Member

dhmlau commented Sep 24, 2020

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.

+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?

@jannyHou
Copy link
Contributor

jannyHou commented Sep 24, 2020

@dhmlau

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

As I see it, the first sections (up to "Reference guides") are for application developers.
The section "Extending LoopBack 4" is for people building extensions, that's why I prefer to keep it a kind of "outside" for docs for app developers. I think we should find new place for this documentation in the future, I'll open a follow-up issue to discuss this further.

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?

- OVERVIEW
- GETTING STARTED
- INSIDE A LOOPBACK APPLICATION
BUILDING LOOPBACK 4 APPLICATION
+ TUTORIALS
+ HOW-TO GUIDES
+ CONCEPTS
+ BEST PRACTICES
+ REFERENCE GUIDE
EXTENDING LOOPBACK 4
+ TUTORIALS (the tutorials in https://loopback.io/doc/en/lb4/Extending-LoopBack-4.html will be moved here)
- COMMUNITY EXTENSIONS
OTHERS(or a better name)
+ CONTRIBUTE TO LOOPBACK 4
-  FAQ
+ MIGRATION GUIDE

@dhmlau
Copy link
Member

dhmlau commented Sep 24, 2020

For "extending LoopBack 4", i assume the original sidebar items are kept unchanged and we're just adding tutorials in it?

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.

@jannyHou
Copy link
Contributor

jannyHou commented Sep 25, 2020

@dhmlau Oh those extension tutorials will be moved to "EXTENDING LOOPBACK 4/TUTORIALS"

I added a note for the menu in #5785 (comment)

@hacksparrow
Copy link
Contributor

On the technical side, there are some pages that need to be read for both application and extension developers.

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.

@bajtos
Copy link
Member Author

bajtos commented Sep 29, 2020

If we can keep the two items always expanded, then I quite like the proposal shown on Janny's screenshot:

Screen Shot 2020-09-23 at 3 52 48 PM

I would add "How-to guides", "Concepts" and "Best-practices" to "Extending LoopBack 4" too.

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 Loo

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 loopback-next and loopback.io repositories. Can we find a way a more decoupled solution please?

As I understand sidebar entries, they are essentially a key-value maps. A typical entry has title, url, output fields, and optionally also children containing an array of nested pages. Can we add another metadata, e.g. collapsible: false, that will be processed by the sidebar template to decide whether an entry can be collapsed or not?

if pageurl.last == item.url or not item.collapsible

I think we also need to pick a different CSS class than active, because active class is not only keeping the section expanded, but it is also adding highlighting to make the active entry stand out.

On the technical side, there are some pages that need to be read for both application and extension developers.

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".

  • IIUC the current proposal, "Reference" is already shared.
  • IMO, "Tutorials" should be always specific to the target audience, i.e. tutorials for app developers will not be applicable to extension developers and vice versa.
  • Is it safe to assume that "How-to guides" are always going to different between apps and extensions? Or at least that there will be enough difference to make it meaningful to create a page dedicated to extension developers, possibly referring to the page for app developers for details that are shared?
  • When it comes to "Concepts", are there any concepts that are specific only to Application or Extension developers? Aren't all concepts applicable to both?

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:

- OVERVIEW
- GETTING STARTED
- INSIDE A LOOPBACK APPLICATION
+ BUILDING LOOPBACK 4 APPLICATIONS
   + TUTORIALS
   + HOW-TO GUIDES
+ EXTENDING LOOPBACK 4
   + TUTORIALS 
   + HOW-TO GUIDES
+ CONCEPTS
+ BEST PRACTICES
+ REFERENCE GUIDES
+ COMMUNITY EXTENSIONS
+ CONTRIBUTE TO LOOPBACK 4
-  FAQ
+ MIGRATION GUIDE

@raymondfeng
Copy link
Contributor

raymondfeng commented Sep 29, 2020

I propose some minor changes on top of @bajtos 's outline:

  • OVERVIEW
  • GETTING STARTED
  • INSIDE A LOOPBACK APPLICATION (=> PREVIEWING A LOOPBACK APPLICATION?)
  • UNDERSTANDING LOOPBACK 4 CONCEPTS (As they are common to applications and extensions)
  • BUILDING LOOPBACK 4 APPLICATIONS
    • TUTORIALS
    • HOW-TO GUIDES
  • EXTENDING LOOPBACK 4
    • TUTORIALS
    • HOW-TO GUIDES
  • BEST PRACTICES
  • REFERENCE GUIDES
  • COMMUNITY EXTENSIONS (Should it be under EXTENDING LOOPBACK 4?)
  • CONTRIBUTE TO LOOPBACK 4 (=> CONTRIBUTING TO LOOPBACK 4)
  • FAQ
  • MIGRATION GUIDE

@jannyHou
Copy link
Contributor

jannyHou commented Sep 30, 2020

Maybe move the description aspect from Extending LoopBack 4 section pages to Concepts.

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).

COMMUNITY EXTENSIONS (Should it be under EXTENDING LOOPBACK 4?)

cc @raymondfeng yep.

I would add "How-to guides", "Concepts" and "Best-practices" to "Extending LoopBack 4" too.

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.

Can we add another metadata, e.g. collapsible: false, that will be processed by the sidebar template to decide whether an entry can be collapsed or not?

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 collapsible: false sounds good and we can create corresponding style for it. I would leave it as implementation details in the follow-up story.


One thing I need to correct is, most of the extension contents belong to HOW-TO GUIDES, not tutorials.

@jannyHou
Copy link
Contributor

A summary of content refactoring:

  • Most of existing contents under extending LoopBack 4 goes to "EXTENDING LOOPBACK 4/HOW-TO GUIDES"
  • "Build large scale Node.js projects with LoopBack 4" should be a series of shared tutorials between app developer and extension developer. Add them to "EXTENDING LOOPBACK 4/TUTORIALS"
  • Extract "Extension point and extensions" into "CONCEPT"
  • Add a tutorial page for "Greeter-extension example"

The new content should look like:

EXTENDING LOOPBACK 4/HOW-TO GUIDES

  • Creating components
  • Creating decorators
  • Contributing REST API
  • Creating Services
  • Creating Servers
  • Extension life cycle
  • Extending OpenAPI specification
  • Extending Model API builder
  • Testing your extension

EXTENDING LOOPBACK 4/TUTORIALS

  • Build large scale Node.js projects with LoopBack 4
  • Greeter-extension example

CONCEPTS

  • Extension point and extensions

@jannyHou
Copy link
Contributor

A summary of the new sidebar:

- OVERVIEW
- GETTING STARTED
- INSIDE A LOOPBACK APPLICATION (rename to PREVIEWING A LOOPBACK APPLICATION?)
+ CONCEPTS (rename to UNDERSTANDING LOOPBACK 4 CONCEPTS?)
+ BUILDING LOOPBACK 4 APPLICATION
    + TUTORIALS
    + HOW-TO GUIDES
+ EXTENDING LOOPBACK 4
    + TUTORIALS 
    + HOW-TO GUIDES (most of contents in https://loopback.io/doc/en/lb4/Extending-LoopBack-4.html will be moved here)
    - COMMUNITY EXTENSIONS
+ BEST PRACTICES
+ REFERENCE GUIDE
+ CONTRIBUTING TO LOOPBACK 4
-  FAQ
+ MIGRATION GUIDE

Implementation tips:

  • If we create nested menu, "BUILDING LOOPBACK 4 APPLICATION" and "EXTENDING LOOPBACK 4" must NOT collapse.
  • Consider using metadata like {collapse: true} to configure the menu.
  • Consider using separator instead of nested menu to distinguish the app vs extension content. It shouldn't be hard to test the 2 proposals, see which one looks better.
     // separator
     BUILDING LOOPBACK 4 APPLICATION
     + HOW-T0 GUIDES
     + TUTORIALS
     EXTENDING LOOPBACK 4
     + HOW-TO GUIDES
     + TUTORIALS
    
     // nested menu
     + BUILDING LOOPBACK 4 APPLICATION
        + HOW-T0 GUIDES
        + TUTORIALS
     + EXTENDING LOOPBACK 4
        + HOW-TO GUIDES
        + TUTORIALS
    

@jannyHou
Copy link
Contributor

jannyHou commented Oct 1, 2020

Created #6477 (need to work on first) and #6478 as follow up stories.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants