O ponto não é a documentção formal, de referência, e sim como usar os Componentes apresentados nela. Mesmo o Javadoc tem vários artigos linkados e exemplos.
Por exemplo, se eu posso instanciar uma Classe que extende JFrame direto no main e funciona, como é que eu iria saber que isso é uma má prática? Preciso de algo que explique que é, porque é, e como fazer o certo.
Esse tipo de coisa precisa ficar linckado na documentação, pra que quando você se deparar com uma classe, veja o link que te leva a um Artigo sobre como usar e como não usar.
Também citei o que deveria ser feito aqui:
Portanto, acredito que seria melhor se as Documentações tivessem várias Soluções prontas onde você pode pesquisar na Documentação a Solução que você precisa, e, ao encontrar você teria aquela “receita de bolo” mostrando quais Componentes usar e como Combiná-los; e os Componentes usados (as Classes, Interfaces, Métodos, etc.) teriam referência para as “receitas de bolo” nas quais eles são utilizados.
Ou seja, a Documentação deve serguir o estilo formal e padrão com as Classes, métodos, parâmetros, tipos de retorno etc., mas também “deve” possuir links para apresentar o que o programador precisa saber, para explicar como utilizar, como não utilizar, dar exemplos, etc.
E isso não é nada fora da realidade, o manual do php permite até mesmo que as pessoas postem notas/contribuições sobre cada tópico.