Хотя большое внимание уделяется справочной документации API, основная часть документации, над которой работают технические писатели (в отличие от разработчиков), является концептуальной документацией. Разработчики редко пишут концептуальную или обучающую документацию.
Инженеры могут написать краткое описание класса в файл и сгенерируют Javadoc. А потом передадут этот Javadoc пользователю, как если бы он представлял собой полный набор документации, хотя справочная документация не расскажет и половину истории.
Справочная документация может быть иллюзией реальной документации
Jacob Kaplan Moss считает, что справочная документация может быть иллюзией реальной документации:
Другие технические писатели, похоже, имеют схожие мнения. В целом, генераторы документации не сообщают намного больше, чем можно узнать, просматривая исходный код. Некоторые люди даже называют автоматически сгенерированные документы прославленным браузером исходного кода.
Справочная документация основана на функциях, а не задачах
Одна из основных проблем со справочной документацией заключается в том, что она основана на функциях, а не на задачах. Что эквивалентно перемещениям по вкладкам через интерфейс и описанию того, что находится на каждой вкладке, что находится в каждом меню и так далее. Такой способ доступа к документации является неэффективным, поскольку пользователи часто организуют свою ментальную модель по задачам, которые они хотят выполнить.
Создавая документацию API, стоит подумать о задачах, которые пользователи захотят выполнить, а затем упорядочить информацию. Нужно обращаться к конечным точкам, объясняя, как выполнять задачи. Пользователи будут ссылаться на справочные документы при поиске правильных параметров, типов данных и других сведений о классе. Но только справочные документы не помогут им в выполнении задач.