Располагайте программу и документацию вместе
Если документация отделена от текста программы, то ее очень трудно обновлять. Следовательно, основная часть вашей документации должна располагаться в комментариях, а не в отдельном документе.
Если вам на самом деле нужна отпечатанная документация высшего качества, то вы можете воспользоваться чем-нибудь похожим на систему Web (для языка Паскаль) или CWeb (для языков Си и Си++) в комбинации с TeX[1]. Я пользуюсь подобной системой под названием arachne, которая была разработана мной для того, чтобы писать свою книгу "Compiler Design in C". (Arachne документирует тексты на Си и Си++, используя в качестве редактора troff). Все эти программы позволяют вам размещать исходный текст программы и документацию в одном файле. Вы можете выделить исходный текст для компиляции, или загрузить этот файл в текстовый процессор, чтобы напечатать единое руководство с исходным текстом и документацией. Эти системы позволяют осуществлять перекрестный поиск идентификаторов в программе и документации, позволяя вам прослеживать связи одной части программы с другой ("этот код используется вон там"), и так далее. Так как для получения печатной версии используется обычный текстовый процессор, то вы можете делать то, чего непросто добиться в комментариях — вставлять рисунки, например.
