Eu sinto falta de mais especificidade da documentação. Muitas vezes vejo objetos que a documentação lista com uns 4 métodos, mas aí observando em outros trechos ou exemplos são utilizados outros métodos que não estavam listados na descrição daquele objeto (o FormController, por exemplo). Então fica muito confuso saber o que cada objeto realmente pode ou não fazer. Senti muito esse problema por estar conhecendo a ferramenta e mais ainda quando comecei a criar um arquivo de auto-complete pro VSCode.
Também já esbarrei com vários casos de páginas que não possuem versão disponível para visualização ou links que vão para outras páginas da TOTVS e essas páginas estão quebradas (infelizmente não lembro agora quais são).
Sinto falta/dificuldade também com os Web Services do próprio Fluig.
Se pegarmos a documentação temos alguns campos, mas se lermos o WSDL veremos muitos mais parâmetros e muitas vezes não sabemos quais parâmetros são importantes/obrigatórios para efetuar a chamada ao WS, ficando assim em várias tentativas e erros. Acredito que toda essa parte de WS deveria ser melhor trabalhada com exemplos e explicações.
Exemplo de problemas comuns, principalmente pra quem não é acostumado com Java, que a documentação poderia facilitar detalhando mais os próprios serviços:
Se eu quero, em algum evento de processo ou em algum dataset, iniciar um novo processo, eu preciso usar o ECMWorkflowEngineService, mas pra conseguir utilizá-lo tive que cadastrar um Serviço no Fluig (acho estranho ter que cadastrar um serviço pro Fluig utilizar sua própria API) e então gastar algum tempo olhando a hierarquia de classes pra então descobrir como, finalmente, ter acesso aos métodos.
var SERVICE_NAME = "ECMWorkflowEngineService", // Nome do Serviço cadastrado no Fluig
SERVICE_PATH = "com.totvs.technology.ecm.workflow.ws.ECMWorkflowEngineServiceService"; // O tempo levado pra entender que preciso instanciar essa classe foi longo
var serviceHelper = ServiceManager.getService(SERVICE_NAME).getBean(),
serviceLocator = serviceHelper.instantiate(SERVICE_PATH)
service = serviceLocator.getWorkflowEngineServicePort(); // E só aqui finalmente ter acesso ao serviço propriamente dito. Algo que não tem na documentação.
Aliás, acho estranho ter que fazer isso sendo que o Fluig possui a WorkflowAPIService, que eu tenho acesso usando simplesmente um var workflowService = fluigAPI.getWorkflowService();
, porém esse serviço não possui nenhum método de criação de processo.
Aliás, a documentação da API SDK também precisa de um melhor cuidado. Talvez ela não seja tão utilizada porque as pessoas preferem cadastrar os serviços no Fluig, mas ao menos quando fui olhar os serviços já listados eu senti muita dificuldade de identificar cada item.
Mas, no geral, a documentação atende bem em várias situações.