История изменений
Исправление swwwfactory, (текущая версия) :
На документацию обычно не предусматриваются бюджеты и по остаточному принципу. Информация очень быстро устаревает и не соответствует реальной картине.
В этом плане doxygen, javadoc системы, а также отличные встроенные системы как в питоне (характерная черта - все доки в коде)
Учить надо не документированию, а эффективным способам передачи информации на уровне смысловой составляющей. Например одни любят читать, другие смотреть диаграммы...
Из ГОСТ-ов не всегда легко извлечь пользу. И не реально все покрыть блок-схемами, хотя и хорошо бы их иметь.
В идеале, документация должна описывать так предметную область, чтобы можно реализовать не зависимо от привязок к ПО. Кто-то ненавидит шарп или перл - если описание отвязано от языка, платформы и т.п. такой доке цены нет. Это как правило интерфейсные типы, IDL? Что там еще есть? В ГОСТ слишком все формализовано и бюрократизировано, можно докопаться к любому проекту на нарушения.
Может быть смотреть в сторону проектов и платформ, имеющих развитые средства, (почти) встроенной в языки документации и генерации, включая поддержку markup? Это языки наверное: python, java, erlang, php, elisp (хотя в нем для других языков слабовата поддержка - всего-то надо навести мышкой на что-то (функция,метод) и появится подсказка с кратким описанием (кстати ищу нормальное решение для emacs+doxygen - doxymacs использую))? И тем не менее код на C в ядре относительно прекрасно документирован. (Помнится C++ задумывался как само-документируемый...)
Исправление swwwfactory, :
На документацию обычно не предусматриваются бюджеты и по остаточному принципу. Информация очень быстро устаревает и не соответствует реальной картине.
В этом плане doxygen, javadoc системы, а также отличные встроенные системы как в питоне (характерная черта - все доки в коде)
Учить надо не документированию, а эффективным способам передачи информации на уровне смысловой составляющей. Например одни любят читать, другие смотреть диаграммы...
Из ГОСТ-ов не всегда легко извлечь пользу. И не реально все покрыть блок-схемами, хотя и хорошо бы их иметь.
В идеале, документация должна описывать так предметную область, чтобы можно реализовать не зависимо от привязок к ПО. Кто-то ненавидит шарп или перл - если описание отвязано от языка, платформы и т.п. такой доке цены нет. Это как правило интерфейсные типы, IDL? Что там еще есть? В ГОСТ слишком все формализовано и бюрократизировано, можно докопаться к любому проекту на нарушения.
Может быть смотреть в сторону проектов и платформ, имеющих развитые средства, (почти) встроенной в языки документации и генерации, включая поддержку markup? Это языки наверное: python, java, erlang, php, elisp (хотя в нем для других языков слабовата поддержка - всего-то надо навести мышкой на что-то (функция,метод) и появится подсказка с кратким описанием)? И тем не менее код на C в ядре относительно прекрасно документирован. (Помнится C++ задумывался как само-документируемый...)
Исходная версия swwwfactory, :
На документацию обычно не предусматриваются бюджеты и по остаточному принципу. Информация очень быстро устаревает и не соответствует реальной картине.
В этом плане doxygen, javadoc системы, а также отличные встроенные системы как в питоне (характерная черта - все доки в коде)
Учить надо не документированию, а эффективным способам передачи информации на уровне смысловой составляющей. Например одни любят читать, другие смотреть диаграммы...
Из ГОСТ-ов не всегда легко извлечь пользу. И не реально все покрыть блок-схемами, хотя и хорошо бы их иметь.
В идеале, документация должна описывать так предметную область, чтобы можно реализовать не зависимо от привязок к ПО. Кто-то ненавидит шарп или перл - если описание отвязано от языка, платформы и т.п. такой доке цены нет. Это как правило интерфейсные типы, IDL? Что там еще есть? В ГОСТ слишком все формализовано и бюрократизировано, можно докопаться к любому проекту на нарушения.
Может быть смотреть в сторону проектов и платформ, имеющих развитые средства, (почти) встроенной в языки документации и генерации, включая поддержку markup? Это языки наверное: python, java, erlang, php, elisp (хотя в нем для других языков слаюовата поддержка - всего-то надо навести мышкой на что-то (функция,метод) и появится подсказка с кратким описанием)? И тем не менее код на C в ядре относительно прекрасно документирован. (Помнится C++ задумывался как само-документируемый...)