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