Всем привет!
Какие у вас есть схемы документирования софта, кода, кто этим занимается, с какой детализацией?
Мое мнение — это не дело самих разработчиков, если ошибаюсь, поправьте аргументированно, плс.
Может есть какие-то общепринятые нормы на этот счет.
Здравствуйте, ivanU, Вы писали:
U>Всем привет! U>Какие у вас есть схемы документирования софта, кода, кто этим занимается, с какой детализацией? U>Мое мнение — это не дело самих разработчиков, если ошибаюсь, поправьте аргументированно, плс. U>Может есть какие-то общепринятые нормы на этот счет.
U>>Всем привет! U>>Какие у вас есть схемы документирования софта, кода, кто этим занимается, с какой детализацией? U>>Мое мнение — это не дело самих разработчиков, если ошибаюсь, поправьте аргументированно, плс. U>>Может есть какие-то общепринятые нормы на этот счет.
PG>По мне писание доки наводит скуку ужасную.
С т.з. эффективности разработчика это трата его времени.
ИМХО должна быть отдельная служба, которая этим занимается, знает предметную область,
умеет читать код, грамотно все оформляет, в редких случаях консультируясь по сложным
техническим моментам у непосредственных разработчиков.
Касаемо пользовательской документации.
Она может быть написана с использвоанием наших ГОСТов или же зарубежных стандатов.
В частности, я пользовался:
IEEE Std 1063-1987 — Standard For Software User Documentation
Тут есть абсолютно всё, что наод.
A>Касаемо пользовательской документации. A>Она может быть написана с использвоанием наших ГОСТов или же зарубежных стандатов. A>В частности, я пользовался: A>IEEE Std 1063-1987 — Standard For Software User Documentation A>Тут есть абсолютно всё, что наод.
A>Занимаются этим техничесие писатели. Читать тут: Профессия технический писатель.
спасибо, почитаю
а касательно документирования самого кода — есть нормы, стандарты?
Здравствуйте, ivanU, Вы писали:
U>Всем привет! U>Какие у вас есть схемы документирования софта, кода, кто этим занимается, с какой детализацией? U>Мое мнение — это не дело самих разработчиков, если ошибаюсь, поправьте аргументированно, плс. U>Может есть какие-то общепринятые нормы на этот счет.
А что ты имеешь ввиду под документированием софта?
Если хелпы и различные руководства, то это действительно не работа программеров.
А если документация архитектуры и дизайна, то кто как ни разработчики должны это делать?
Комментарии в коде тоже никто кроме разработчиков не напишет.
Здравствуйте, ivanU, Вы писали:
A>>Касаемо пользовательской документации. A>>Она может быть написана с использвоанием наших ГОСТов или же зарубежных стандатов. A>>В частности, я пользовался: A>>IEEE Std 1063-1987 — Standard For Software User Documentation A>>Тут есть абсолютно всё, что наод.
A>>Занимаются этим техничесие писатели. Читать тут: Профессия технический писатель.
U>спасибо, почитаю
U>а касательно документирования самого кода — есть нормы, стандарты?
Есть такие штуки как javadoc, perldoc, rdoc и прочие аналоги для различных языков программирования. Эти средства требуют комментариев определенного вида для автоматической генерации документации. В принципе, их правила форматирования можно брать за основу.
[skip]
B>А если документация архитектуры и дизайна, то кто как ни разработчики должны это делать?
Да, имелось в виду это.
Тут есть какие-то общепринятые нормы, стандарты (например для внешнего IT аудита) или обычно решается индивидуально на корпоративном уровне?
Если у вас документацией, ее оформлением и пр занимаются сами разработчики, какой процент времени от их общей работы это занимает?
Если описывать каждую функцию, ее параметры, связи и пр в отдельном большом документе, собственно на саму разработку останется гораздо меньше времени.
Интересует как нужно это делать "по хорошему", может нужно будет обосновывать руководству необходимость открывать новые вакансии, может есть ссылки
по этому поводу.
B>Комментарии в коде тоже никто кроме разработчиков не напишет.
Простые комменты в коде я так понял руководство не устроят.
U>[skip]
B>>А если документация архитектуры и дизайна, то кто как ни разработчики должны это делать?
U>Да, имелось в виду это. U>Тут есть какие-то общепринятые нормы, стандарты (например для внешнего IT аудита) или обычно решается индивидуально на корпоративном уровне?
На аудитах будут проверять только то,
что вы этим осознанно занимаетесь (документируете, проводите ревью и апдейтите когда надо).
Форма их интересовать не будет.
На корпоративном уровне надо будет решить именно то, о чем ты спрашиваешь,
т.е. какая дока и насколько детальной она должна быть.
Есть два полюса:
— ноль документации
— документированн каждый бит и существуют все мыслимые traceability...
Ты, как разработчик не сможешь решить за всю контору, что именно
в вашем случае надо документировать.
Например у нас документируются:
— общая архитектура системы из которой видны основные компоненты и связи между ними
— детально описаны все публичные интерфесы компонент.
— описана динамика работы системы на примерах самых важных use case
— детально описаны все интерфейсы с внешними системами и железом.
Все это обязано быть в актуальном состоянии.
Документация частично в UML, частично текст, если проще описывать текстом.
Детали реализации тоже описаны, но не для всякого чиха.
На документирование уходит не больше 5% времени.
Здравствуйте, ivanU, Вы писали:
U>Всем привет! U>Какие у вас есть схемы документирования софта, кода, кто этим занимается, с какой детализацией? U>Мое мнение — это не дело самих разработчиков, если ошибаюсь, поправьте аргументированно, плс. U>Может есть какие-то общепринятые нормы на этот счет.
Не совсем понятно что вы понимаете под документированием ПО?
Если понимать весь жизненный цикл разработки ПО от сбора первоначальных требований, до сдачи программного продукта, то
на каждом этапе свои документы у каждого участника.
1. Требования и виденье продукта — бизнес аналитик (используем Vision из RUP)
2. Проектны план — менеджер проекта
3. ТЗ — бизнес аналитик, системный аналитик (используем SRS из RUP)
4. Описание архитектуры — архитектор (используем SAD из RUP)
5. Документация программиста — программист — только он сможет написать комментарии к своему коду (используем Sandcastle для dotNET)
6. Test cases и check lists — тестеры (используется Test Plan и Test Evaluation Summary из RUP)
7. Пользовательская документация — технический писатель — формат доки тот, который устраивает заказчика
З.Ы. Набор документации зависит сильно от используемых методологий разработки. Сейчас собираемся уходить от более жесткой методологии к более гибкой (SCRUM) с целью снижения объемов документации и снижением временных затрат на поддержание документации
Здравствуйте, ivanU, Вы писали:
U>Всем привет! U>Какие у вас есть схемы документирования софта, кода, кто этим занимается, с какой детализацией? U>Мое мнение — это не дело самих разработчиков, если ошибаюсь, поправьте аргументированно, плс. U>Может есть какие-то общепринятые нормы на этот счет.
Здравствуйте, ivanU, Вы писали:
U>>>Всем привет! U>>>Какие у вас есть схемы документирования софта, кода, кто этим занимается, с какой детализацией? U>ИМХО должна быть отдельная служба, которая этим занимается, знает предметную область, U>умеет читать код
По моему мнению документирование софта (описание взаимодействия с программным продуктом, можно просто хелпом обозвать) и документирование кода это разные вещи. При написании доков к софту, не нужно впринципе читать код.
У нас этим занимаются технические писатели. На вход им дается ТТ, ТЗ, небольшое описание продукта от разработчика и собственно сам продукт.
Здравствуйте, bkat, Вы писали:
B>А что ты имеешь ввиду под документированием софта? B>Если хелпы и различные руководства, то это действительно не работа программеров. B>А если документация архитектуры и дизайна, то кто как ни разработчики должны это делать? B>Комментарии в коде тоже никто кроме разработчиков не напишет.
А если хелп и мануалы по коду герерятся? Как например здесь ?
UNIX way — это когда тебе вместо туалетной бумаги дают топор, рубанок и карту близлежащего леса
Здравствуйте, catBasilio, Вы писали:
B>Здравствуйте, bkat, Вы писали:
B>>А что ты имеешь ввиду под документированием софта? B>>Если хелпы и различные руководства, то это действительно не работа программеров. B>>А если документация архитектуры и дизайна, то кто как ни разработчики должны это делать? B>>Комментарии в коде тоже никто кроме разработчиков не напишет.
B>А если хелп и мануалы по коду герерятся? Как например здесь ?
Если продукт для программеров (типа Qt фреймфорка), то такой подход вполне разумен.
Здравствуйте, bkat, Вы писали:
B>Здравствуйте, catBasilio, Вы писали:
B>>Здравствуйте, bkat, Вы писали:
B>>>А что ты имеешь ввиду под документированием софта? B>>>Если хелпы и различные руководства, то это действительно не работа программеров. B>>>А если документация архитектуры и дизайна, то кто как ни разработчики должны это делать? B>>>Комментарии в коде тоже никто кроме разработчиков не напишет.
B>>А если хелп и мануалы по коду герерятся? Как например здесь ?
B>Если продукт для программеров (типа Qt фреймфорка), то такой подход вполне разумен.
Здравствуйте, catBasilio, Вы писали:
B>Вот я сильно сомневаюсь доку как в qt4 (http://doc.trolltech.com/4.6/overviews.html) напишет простой программер (не технический писатель).
Как конкретно пишут подобную доку в trolltech (пардон в Nokia) я не знаю.
Скорей всего часть пишут программеры, а часть — технические писатели.
Детальное описание API — это явно из комментариев в коде.
Какие-то обзорные вещи и координация всего до кучи — это скорее всего технические писатели,
или люди, играющие эту роль
