Хабр Курсы для всех
РЕКЛАМА
Большая витрина: от крупнейших школ до частных авторов. Сравнивайте по цене, длительности, формату и выбирайте самый подходящий курс!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 43
Нда… Мне явно нужен хороший техписатель. Где бы найти такого на постоянно-фрилансной основе за разумные средства?
Сам ищу :) Тут на носу стадия ТП по крупному проекту. А всех техписов разобрали на другие проекты. Значит, буду сам писать.
А почему это хороший техписатель будет стоить разумных средствов? :) Типа, слова писать — наука не точная, не то что девелопмент, потому и стоит дешевле?
На HH поищите, после 10-15 собеседований можно найти светлую голову. Не в смысле блондинку, а человека адекватного (хотя, может повезед и найдется адекватная блондинка :)).
Да по-моему в нашей деревне всё плохо. На хх голяк. Делопроизводителя (!!) адекватного поиски заняли 4 месяца.
Да, свободный рынок как-то не очень работает. Я, например, ни разу не менял работу через агентство. Все время по знакомству переводился. А теперь вообще командой кочуем. Несколько раз делал попытки собеседоваться через ХХ. Бесполезная трата времени. Кадровикам непонятно, за что мне вообще деньги платят. Так на любой работе, связанной с «высшими материями», где нужно не формальное соответствие, а адекватность.
Проще всего принять на работу админа начального уровня. Он только в дверь входит, а я уже знаю, подходит чувак или нет :). А вот с другими не так просто.
Проще всего принять на работу админа начального уровня. Он только в дверь входит, а я уже знаю, подходит чувак или нет :). А вот с другими не так просто.
Когда надо было — искал несколько месяцев, но нашел :)
Да, непросто все, но возможно :)
Да, непросто все, но возможно :)
А вам это так надо? Собственно стандарт нужен в лучшем случае при работе с гос-проектом, а в остальных случаях есть более специализированные и современные варианты. Я раньше тоже по ГОСТУ писал, для гос-проектов как раз, но из частных заказчиков это мало кому надо.
Собственно, госзаказы, да. Все собираются из одной базы, потому мне бы один раз написали всё, дальше уж по аналогии бы корректировал под конкретные случаи.
Мне кажется сейчас проще найти примеры ТЗ в сети и корректировать их, чем искать техписа знакомого с ГОСТами и их типичными формулировками, ну либо писать самому, ничего смертельно сложного в этом нету. Ведь техпису тоже надо объяснить о чем надо писать собственно, а так вы сами знаете и лучше можете сформулировать по примерам. Главное правило составления — устранение разночтений одних и тех же предложений.
Благодарность за статью, ценный труд.
что-то подсказывает мне, читать госты, обращать внимание на типичные формулировки и знать их типичные последствия, необходимо и тролькиллеру и тому кто сдает проект.
что-то подсказывает мне, читать госты, обращать внимание на типичные формулировки и знать их типичные последствия, необходимо и тролькиллеру и тому кто сдает проект.
Спасибо, реализовал давний замысел зафиксировать накопленные знания. Теперь буду ссылку давать на свой же топик вместо того, чтобы по сто раз одно и то же объяснять :)
можете предложить некоторое количество ссылок на литературу?
я вот могу открыть списочек: rutracker.org/forum/viewtopic.php?t=256628
я вот могу открыть списочек: rutracker.org/forum/viewtopic.php?t=256628
Проект на 15 человекомесяцев, требований со стороны заказчика по документированию нет, какие документы посоветуете написать?
Я, со своим крошечным опытом и помощью опытных ребят рассчитывал на эскизник, техпроект и руководство оператора.
Я, со своим крошечным опытом и помощью опытных ребят рассчитывал на эскизник, техпроект и руководство оператора.
А потом окажется, что заказчик «имел в виду» полный комплект, который при сертификации обязательно нужен. :-) Вся потребность в документации по ГОСТу, на мой взгляд, и сводится к сертификации или иным подобным мероприятиям. В противном случае выгоднее писать так, чтобы пользователю было удобно и понятно, а не по ГОСТу.
Если перефразировать Догму, — У создателей ГОСТов прекрасное чувство юмора. Взять хотя бы бумажную документацию на 1С.
Если перефразировать Догму, — У создателей ГОСТов прекрасное чувство юмора. Взять хотя бы бумажную документацию на 1С.
А как это, удобно и понятно? Есть какие-то схемы, примеры, списки документов?
Попробую в двух словах дать выжимку своих ощущений от этой темы.
(В идеале) должно быть удобно и понятно пользователю продукта. Иначе говоря, тут две переменных — продукт и его целевая аудитория.
Неказистый (недостаточно хорошо спроектированный) продукт порождает сложную документацию. Не в последнюю очередь потому, что разработчики и сами не понимают, что представляет из себя этот продукт (к примеру, в вашем случае это может быть из-за недостаточно узкого определения продукта и недостаточно проработанных требований к нему; далее отсылаю к Алану Куперу).
Клёвый продукт документировать легко, потому что целевая аудитория чётко определена. Автору тогда не нужно писать все возможные варианты документации, потому что он не представляет, чего захочется людям.
Простейший пример: *никсовые маны. Информационная плотность манов очень велика, воды там минимум, потому что они ориентированы на очень узкую ЦА, системных администраторов и внимательных энтузиастов. Никому не придёт в голову писать для утилиты wc набор (five minute intro, ten minute intro, fifteen minute intro, faq, api reference, developer's manual).
С другой стороны, если совокупная сложность продукта превышает определённый порог, иногда полезнее написать книгу, чем стописят манов, факов и экзамплов. Примеры из жизни: sendmail, bind. Книгами по подобным инструментам люди пользуются с куда как большим удовольствием, чем «родной» документацией. Почему так? И почему, скажем, разработчикам байнда было сразу не написать увлекательную книжку, как поступили Крикет и Ли?
Отдельный разговор — внутренняя документация для разработчиков. Для них иногда самая клёвая документация — это UML-диаграммы. И больше не надо ничего.
И вот как на это всё можно натянуть ГОСТ? На мой взгляд, никак. Польза ГОСТа, равно как и прочих стандартов, в, простите, стандартизации. То есть когда число продуктов начинает превышать какой-то обозримый минимум, возникает идея, что всё должно быть единообразно — для упрощения и ускорения процессинга этих самых продуктов. Если для академической среды это хорошо, не факт, что это будет хорошо для конечного потребителя.
Другой момент — если люди не хотят напрягать мозг насчёт документации, они могут применить стандарты, и сэкономить на этом. Если формат продукта такой, что это допустимо, ничего страшного нет. Если продукт клёвый (см. выше), возможно, есть смысл задуматься, как применение стандартов отразится на конечных пользователях. (Хотя мне кажется, у авторов клёвых продуктов вообще изначально забота о пользователях выше.)
Какие-то схемы, примеры и списки я приводить, пожалуй, не буду — кажется, особого смысла нет. Могу сказать, что для текущего продукта выбрал неформальный формат для руководства пользователя — почти полностью отказался от безличных оборотов, формальных конструкций языка, и вообще ориентируюсь на то, чтобы развлекать читателя. Насколько это оправданно — покажет время.
(В идеале) должно быть удобно и понятно пользователю продукта. Иначе говоря, тут две переменных — продукт и его целевая аудитория.
Неказистый (недостаточно хорошо спроектированный) продукт порождает сложную документацию. Не в последнюю очередь потому, что разработчики и сами не понимают, что представляет из себя этот продукт (к примеру, в вашем случае это может быть из-за недостаточно узкого определения продукта и недостаточно проработанных требований к нему; далее отсылаю к Алану Куперу).
Клёвый продукт документировать легко, потому что целевая аудитория чётко определена. Автору тогда не нужно писать все возможные варианты документации, потому что он не представляет, чего захочется людям.
Простейший пример: *никсовые маны. Информационная плотность манов очень велика, воды там минимум, потому что они ориентированы на очень узкую ЦА, системных администраторов и внимательных энтузиастов. Никому не придёт в голову писать для утилиты wc набор (five minute intro, ten minute intro, fifteen minute intro, faq, api reference, developer's manual).
С другой стороны, если совокупная сложность продукта превышает определённый порог, иногда полезнее написать книгу, чем стописят манов, факов и экзамплов. Примеры из жизни: sendmail, bind. Книгами по подобным инструментам люди пользуются с куда как большим удовольствием, чем «родной» документацией. Почему так? И почему, скажем, разработчикам байнда было сразу не написать увлекательную книжку, как поступили Крикет и Ли?
Отдельный разговор — внутренняя документация для разработчиков. Для них иногда самая клёвая документация — это UML-диаграммы. И больше не надо ничего.
И вот как на это всё можно натянуть ГОСТ? На мой взгляд, никак. Польза ГОСТа, равно как и прочих стандартов, в, простите, стандартизации. То есть когда число продуктов начинает превышать какой-то обозримый минимум, возникает идея, что всё должно быть единообразно — для упрощения и ускорения процессинга этих самых продуктов. Если для академической среды это хорошо, не факт, что это будет хорошо для конечного потребителя.
Другой момент — если люди не хотят напрягать мозг насчёт документации, они могут применить стандарты, и сэкономить на этом. Если формат продукта такой, что это допустимо, ничего страшного нет. Если продукт клёвый (см. выше), возможно, есть смысл задуматься, как применение стандартов отразится на конечных пользователях. (Хотя мне кажется, у авторов клёвых продуктов вообще изначально забота о пользователях выше.)
Какие-то схемы, примеры и списки я приводить, пожалуй, не буду — кажется, особого смысла нет. Могу сказать, что для текущего продукта выбрал неформальный формат для руководства пользователя — почти полностью отказался от безличных оборотов, формальных конструкций языка, и вообще ориентируюсь на то, чтобы развлекать читателя. Насколько это оправданно — покажет время.
На самом деле в самих ГОСТ 19 серии (ЕСПД — единая система программной документации) написано — допускается устранять разделы и вводить новые. То есть, вы можете практически полностью изменить документ (обязательно должны быть титульный лист, содержание и аннотация) под ваши цели.
В каких документах из числа предлагаемых ГОСТ представлять информацию? Пожалуйста:
1. API, диаграммы классов, примеры написания кода — «Руководство программиста» (документ 13);
2. Конфигурирование, установка, удаление, использование системных утилит — «Руководство системного программиста» (документ 32). Тут стоит сказать, что в момент создания ГОСТов этой серии «системными программистами» называли админов, в обязанности которых входило дописывание ОС под нужды программеров;
3. Инструкции для конечного пользователя — «Руководство оператора» (документ 34).
Не можете подобрать подходящий документ — вводите свой со свободным номером.
В каких документах из числа предлагаемых ГОСТ представлять информацию? Пожалуйста:
1. API, диаграммы классов, примеры написания кода — «Руководство программиста» (документ 13);
2. Конфигурирование, установка, удаление, использование системных утилит — «Руководство системного программиста» (документ 32). Тут стоит сказать, что в момент создания ГОСТов этой серии «системными программистами» называли админов, в обязанности которых входило дописывание ОС под нужды программеров;
3. Инструкции для конечного пользователя — «Руководство оператора» (документ 34).
Не можете подобрать подходящий документ — вводите свой со свободным номером.
Да, есть явный конфликт между структурой ГОСТ и требованиями по «эргономике текста». Наверное, лучше все-таки, иметь стандартное РП и параллельно инструктивный материал по ролям участников процесса (некая разновидность технологической инструкции). В свое время я экспериментировал со свободной формой. Не всем она по душе и не все разделяют энтузиазм создателей системы.
По внутренней документации. Даже в нашем маленьком стартапе программисты не могут работать без постановок, которые готовят аналитики. У программистов нет фантазии, им это вообще не нужно. Постановка может содержать уже и Use Case, и эскизы интерфейсов и все, что угодно, чтобы программист понял задачу.
По книжкам. Документация по ГОСТ сделана таким образом, что она может появляться вместе с системой, параллельно. Не думаю, что популярную книжку можно написать до того, как появится предмет описания. А вот потом, глядя на готовую систему и (убогую) документацию к ней, можно уже выдать любой материал для любой аудитории, с картинками и цветными врезками.
По внутренней документации. Даже в нашем маленьком стартапе программисты не могут работать без постановок, которые готовят аналитики. У программистов нет фантазии, им это вообще не нужно. Постановка может содержать уже и Use Case, и эскизы интерфейсов и все, что угодно, чтобы программист понял задачу.
По книжкам. Документация по ГОСТ сделана таким образом, что она может появляться вместе с системой, параллельно. Не думаю, что популярную книжку можно написать до того, как появится предмет описания. А вот потом, глядя на готовую систему и (убогую) документацию к ней, можно уже выдать любой материал для любой аудитории, с картинками и цветными врезками.
Думаю, последнее можно обобщить — документация по любому стандарту может появляться вместе с системой.
Популярная книжка, конечно, требует какой-то живой экосистемы продукта, но хочется подчеркнуть, что дефолтная документация не должна быть убогой. Как раз наоборот.
Популярная книжка, конечно, требует какой-то живой экосистемы продукта, но хочется подчеркнуть, что дефолтная документация не должна быть убогой. Как раз наоборот.
Документация убогая, когда пишущий:
— плохо умеет выражать мысли на русском языке
— ленив или слабо мотивирован
— слабо разбирается в предмете описания
— не владеет всем объемом исходных данных по независящим от него обстоятельствам (например, не подогнали вовремя описываемый модуль)
Когда все пункты выполнены, документация получается отличная. Даже в тисках структуры ГОСТа
— плохо умеет выражать мысли на русском языке
— ленив или слабо мотивирован
— слабо разбирается в предмете описания
— не владеет всем объемом исходных данных по независящим от него обстоятельствам (например, не подогнали вовремя описываемый модуль)
Когда все пункты выполнены, документация получается отличная. Даже в тисках структуры ГОСТа
Да нету никакого конфликта :) Мы по ГОСТ работаем и пишем вполне себе приятные тексты на литературном русском языке :)
Просто не все понимают, что ГОСТ оставляет ОЧЕНЬ много свободы для адаптации документов под конкретные задачи или ввода новых документов (хотите инструктивный материал — ввели новый документ и вперед! :)). А там это черным по белому написано :)
Просто не все понимают, что ГОСТ оставляет ОЧЕНЬ много свободы для адаптации документов под конкретные задачи или ввода новых документов (хотите инструктивный материал — ввели новый документ и вперед! :)). А там это черным по белому написано :)
Есть типовое решение подобных вопросов, которое я знаю (оно не обязательно верное). Далее субъективное мнение.
О пользе эскизного проекта я не слышал. Образно говоря, ЭП нужен для изъятия дополнительных дензнаков у заказчика. Вам в итоге можно ограничиться двумя(тремя) документами.
Пишете Пояснительную записку к техпроекту (П2), куда включаете необходимый вам контент в виде разделов по РД50 и руководство пользователя по ГОСТ. Если у вас приложение сложное в обслуживании, сделайте еще Руководство администратора (отдельная книжечка). По сути это просто глава из РП, но так будет проще согласовывать. Заодно там будет минимально необходимый технический контент стадии РД (см. ГОСТ 34.602)
Если заказчик вдруг запаникует и заговорит о ГОСТах, вы раздергаете контент П2 на отдельные «обеспечения» и все будет хорошо.
О пользе эскизного проекта я не слышал. Образно говоря, ЭП нужен для изъятия дополнительных дензнаков у заказчика. Вам в итоге можно ограничиться двумя(тремя) документами.
Пишете Пояснительную записку к техпроекту (П2), куда включаете необходимый вам контент в виде разделов по РД50 и руководство пользователя по ГОСТ. Если у вас приложение сложное в обслуживании, сделайте еще Руководство администратора (отдельная книжечка). По сути это просто глава из РП, но так будет проще согласовывать. Заодно там будет минимально необходимый технический контент стадии РД (см. ГОСТ 34.602)
Если заказчик вдруг запаникует и заговорит о ГОСТах, вы раздергаете контент П2 на отдельные «обеспечения» и все будет хорошо.
1. По поводу «Чертежей формы документа (видеокадра)»: Очень полезный документ для визуализации/управления технологическими процессами, особенно когда согласован с технологами :)
2. По поводу «регламента работы службы эксплуатации»: он полностью вытекает из ПЗ, схемы функц. структуры и РЭ, иначе мы автоматизируем сферического коня в вакууме :)
Другое дело, когда эту информацию предоставляет Заказчик в виде исходных данных, но это как договор составлен :)
3. ПЗ — это обычно самый ожидаемый и в итоге самый разочаровывающий документ, т.к. Исполнитель тупо запихивает в него ТЗ.
2. По поводу «регламента работы службы эксплуатации»: он полностью вытекает из ПЗ, схемы функц. структуры и РЭ, иначе мы автоматизируем сферического коня в вакууме :)
Другое дело, когда эту информацию предоставляет Заказчик в виде исходных данных, но это как договор составлен :)
3. ПЗ — это обычно самый ожидаемый и в итоге самый разочаровывающий документ, т.к. Исполнитель тупо запихивает в него ТЗ.
По п.1 есть еще документ «Состав выходных данных (сообщений)», куда можно поместить все необходимые эскизы. Там же обычно живут и отчетные формы.
По п.2. Часто приходится автоматизировать несуществующие бизнес-процессы. Чтобы опираться хоть на что-то, придумывается некий виртуальный бизнес-процесс, под который пишутся технические документы. Это ненормальная ситуация, но встречается сплошь и рядом. В нашей стране все еще свято верят в то, что с помощью хитрой программы можно решить проблемы бизнеса.
По п.2. Часто приходится автоматизировать несуществующие бизнес-процессы. Чтобы опираться хоть на что-то, придумывается некий виртуальный бизнес-процесс, под который пишутся технические документы. Это ненормальная ситуация, но встречается сплошь и рядом. В нашей стране все еще свято верят в то, что с помощью хитрой программы можно решить проблемы бизнеса.
Сам стандарт морально устарел, но общая идея и методология актуальная до сих пор. Используя его, например совместно с ISO 15288 или 12207, вы получаете хороший инструмент.
Статья и так распухла до безобразного размера, чтобы ее наполнять еще и описанием жизненного цикла. Это будет уже книжка, а не статья.
Во что я твердо верю, это в то, что при желании и ясном представлении цели можно сделать очень многое. Даже безо всяких стандартов. У нас в стране светлые головы еще не перевелись.
Во что я твердо верю, это в то, что при желании и ясном представлении цели можно сделать очень многое. Даже безо всяких стандартов. У нас в стране светлые головы еще не перевелись.
Раньше несоблюдение стандартов преследовалось по закону. Сейчас выполнение стандартов не обязательно — вместо них пытаются ввести новые виды документов.
Стандартизация — тормоз прогресса. Если бы проекты писались по всем стандартам, то многого, что у нас сейчас есть не было.
Стандартизация — тормоз прогресса. Если бы проекты писались по всем стандартам, то многого, что у нас сейчас есть не было.
Стандарты призваны обеспечить совместимость между изделиями, разрабатываемыми в разных уголках страны. Представьте, что будет, если производители смесителей для ванн свой вид резьбы придумают и забью на стандарт? Правильно, никто не сможет установить из смесители и продажи не пойдут.
ГОСТ на программную документацию разрабатывался для упоорядочивания процесса разработки и обеспечения обмена информацией между разработчиками, трудящимися в различных учреждениях. Если вам придется синхронизировать процесс разработки с какой-либо сторонней организацией (заказать что-то на аутсорсинг, например), ГОСТ позволит вам ничего не изобретая составить перечень документов и запросить их подготовку в ТЗ. А исполнитель не будет ломать голову над форматом изложения, например, правил написания конфига, а откроет ГОСТ, найдет структуру соответствующего документа и ее заполнит.
ГОСТ на программную документацию разрабатывался для упоорядочивания процесса разработки и обеспечения обмена информацией между разработчиками, трудящимися в различных учреждениях. Если вам придется синхронизировать процесс разработки с какой-либо сторонней организацией (заказать что-то на аутсорсинг, например), ГОСТ позволит вам ничего не изобретая составить перечень документов и запросить их подготовку в ТЗ. А исполнитель не будет ломать голову над форматом изложения, например, правил написания конфига, а откроет ГОСТ, найдет структуру соответствующего документа и ее заполнит.
Посмотрите мой материал на Хабре по американскому стандарту ИТС. Они там даже функциональные требования стандартизировали, а не только формы документов. Потому что транспортные системы, выполненные по стандарту, помогут дяде Сэму организовать эвакуацию целых штатов, управлять дорожным движением всей страны, контролировать транспортные потоки и еще много вкусностей для Большого брата. Ради этого стоит потратиться на разработку стандарта и требовать его исполнения.
Тем, кто разрабатывает АСУТП, очень рекомендую ознакомиться с книгой Ю.Н. Федорова «Справочник инженера по АСУТП: проектирование и разработка», хорошая систематизация, весьма помогает в работе.
Отличный материал выдали! Спасибо. Хорошо структурирован.
Что же касается самого ГОСТ, то при разумном его использовании, можно создавать внятные и полезные документы. Если доки не просто формальная отписка и написаны толковыми спецами, то по ним вполне можно вникнуть как работает система, посмотреть на нее с разных аспектов.
В чем готовите документы, если не секрет? Трудяга Ворд?
Слышал, что наиболее эффективно готовить в спецпакетах — Adobe FrameMaker и иже с ним. Сам никогда во FrameMaker, но судя по описанию принципа работы, подготовка комплекта документов в нем более гибка, чем в Ворде.
Что же касается самого ГОСТ, то при разумном его использовании, можно создавать внятные и полезные документы. Если доки не просто формальная отписка и написаны толковыми спецами, то по ним вполне можно вникнуть как работает система, посмотреть на нее с разных аспектов.
В чем готовите документы, если не секрет? Трудяга Ворд?
Слышал, что наиболее эффективно готовить в спецпакетах — Adobe FrameMaker и иже с ним. Сам никогда во FrameMaker, но судя по описанию принципа работы, подготовка комплекта документов в нем более гибка, чем в Ворде.
Я слышал, что ГОСТ 34 выпускали в спешке. И за 20 лет он конечно успел устареть.
Но в СССР ГОСТы обновлялись гораздо чаще.
Все равно, это лучше, чем ничего. Обычно ТЗ пишут в форме потока сознания, а все схемы исполнитель рисует от руки.
Но в СССР ГОСТы обновлялись гораздо чаще.
Все равно, это лучше, чем ничего. Обычно ТЗ пишут в форме потока сознания, а все схемы исполнитель рисует от руки.
Автоматизированная система в представлении составителей ГОСТ представляет собой совокупность железа, софта и каналов связи
… и персонала. Если система работает без участия человека, то она уже автоматическая (например, пожаротушения), а не автоматизированная.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Документирование по ГОСТ 34* — это просто