Документация и управление версиями
Неинициализированные переменные. (Или современные языки покончили с этим?)
6 ответов
Это действительно зависит от вашей команды. Там, где я работаю, мы храним документацию в вики, на которую есть ссылка на сайт нашей команды. В целях поставки документации вики-страницу можно экспортировать, и мы запускаем ее через синтаксический анализатор, который «приукрашивает» внешний вид документации для клиентов.
Хранение документации с кодом (обычно в вашем исходном репозитории) неплохая идея. Просто убедитесь, что они разделены. Например, сохраните папку docs , которая находится на том же уровне, что и ваша папка src в вашем репозитории. Таким образом, вы можете быстро отправить текущую документацию, вы можете легко отслеживать изменения, и любой, кто не знаком с проектом, может немедленно подключиться, не обращаясь за информацией в разные места.
Это интересный вопрос - в основном то, что другие говорят о сгенерированной документации, правильно, исходные файлы и шаблоны / etc. должны храниться в системе контроля версий и генерироваться в процессе сборки.
Что касается требований / спецификаций / и т.д. документации, я работал в обоих направлениях, и я очень предпочитаю использовать SharePoint или портал Wiki / документов, который предназначен для совместного использования / управления версиями документов. Причина в том, что большинству людей, не являющихся разработчиками, неудобно работать с системами управления версиями, а вы не Не получите никаких преимуществ интеллектуального слияния, если вы используете двоичный формат, например Word. Кроме того, приятно иметь доступ через Интернет, чтобы вы могли ссылаться на документы и работать с ними в распределенной команде без необходимости установки дополнительного программного обеспечения.
Если вы пишете документацию пользователя с поддержкой версий, связанную с каждым выпуском продукта, то имеет смысл поместить документацию в систему контроля версий вместе с соответствующим выпуском продукта.
Если вы пишете внутренняя документация разработчика, используйте автоматизированную внутреннюю документацию по исходному коду (javadoc, doxygen, .net-аннотации и т. д.) для документации уровня исходного кода и вики проекта для документации уровня проектирования.
Я думаю, что большинство из нас в отрасли на самом деле не следуют лучшим практикам, и это, конечно, также во многом зависит от вашей ситуации.
В гибкой среде, где у вас будет очень итеративный процесс выпуска, вам захочется «путешествовать налегке». В данном конкретном случае предложение Джейсона об отдельной Wiki действительно отлично работает.
В модели водопада / большого взрыва у вас будет лучшая возможность получать приличное обновление документации с каждым новым выпуском. Также вам нужно будет четко задокументировать, какая версия требований была согласована, и иметь массу документации для каждого крошечного изменения, которое вы вносите в требования (из-за воздействия, которое оно оказывает на последующих этапах). Часто, если документация может существовать вместе с исходным кодом с контролируемой версией, это лучший вариант.
Используете ли вы какую-либо автоматическую документацию или она полностью ручная? Предполагая, что вы используете систему автоматической документации, документация более или менее генерируется «на лету» и будет частью самого кода.
Для меня (при условии, что это возможно с любым кодом, который вы используете), это был бы предпочтительный метод обработки, так как вам вообще не нужно поддерживать исходный код документации.