É confusa sim, eu acho.

Por exemplo, ela geralmente não coloca o import das dependências, e nem sempre são classes/tipos/... do proprio next, então é dificil adivinhar só pelas opções dadas pela IDE.

Outra coisa que confunde é porque existem dois tipos diferentes de router, o pages e o app, aparentemente sendo o app o mais recente. Quando você vai pesquisar na internet acaba encontrando soluções para o tipo errado de router.

Enfim, estou começando a trabalhar com nextjs no meu projeto de saas que até postei aqui, estou gostando mas também tive dificuldade com a documentação