Оставить заявку

Марина (Все сообщения пользователя)

Внимание! У нас сбои с почтовым сервером! Если не пришло письмо о регистрации или смене пароля напишите нам на info@techwriters.ru! 
@twriters
 obmen_soobsheniyami.pngчат для технических писателей в Telegram

 Зарегистрируйтесь
Выбрать дату в календареВыбрать дату в календаре

Страницы: 1 2 След.
Комплект программной документации на составную программу (систему), Вопрос о том, как корректно сформировать набор документов для сложной программы, имеющей в своем составе несколько модулей, в т.ч. стороннее ПО (ОС)
 
Про формуляр ничего не подскажу - никогда писать не приходилось.

Замечание про 34 ГОСТ снимаю. Итог работы по 34 ГОСТу - автоматизированный процесс "под ключ". Т. е. не только написано ПО, но и установлено, настроено, при необходимости закуплено и установлено железо, на котором оно будет работать, протянуты сети, обучен персонал, написаны инструкции для разных ролей работы с системой и т.д. Не обязательно все это делает один исполнитель, но важно, что это должно быть прописано в договоре и ТЗ и выполнено. Если итог работы - диск с кодом, 34 ГОСТ не нужен.
Комплект программной документации на составную программу (систему), Вопрос о том, как корректно сформировать набор документов для сложной программы, имеющей в своем составе несколько модулей, в т.ч. стороннее ПО (ОС)
 
На все вопросы не отвечу, так, отдельные мысли на тему:

Если это система управления оборудованием, и вы же будете заниматься её внедрением, наверно, 34 ГОСТ будет более уместен, чем 19.

Разбиением систем на компоненты занимается, конечно, не техписатель, а "начальство" - менеджер проекта, системный архитектор и т.д. По большому счету и писать все программную документацию должен не техписатель, его прямая обязанность - пользовательская документация, остальное опционально. Список документов начальство согласовывает с заказчиком где-то на стадии подписания договора, и в этом списке документы перечисляются уже с кодами. Если договор подписан, программисты работают, а списка документов нет, скорее всего, как они будут обозначены - не очень принципиальный вопрос.

Если по 19 госту, мне больше нравится первый вариант - меньше писанины, которую никто не читает. Зачем, например, руководство оператора для каждого компонента? Формуляр - это, кажется что-то из древности, для хранения в архивах. Если программа устанавливается исполнителем на компьютеры заказчика, вполне можно обойтись без него (тем более в 5 экземплярах).


Из ГОСТ 19.402-78 Описание программы:
[QUOTE]
6. В разделе «Описание логической структуры» должны быть указаны:[LIST]
[*]алгоритм программы;
[*]используемые методы;
[*]структура программы с описанием функций составных частей и связи между ними;
[*]связи программы с другими программами.
[/LIST][/QUOTE]

В пункт "[COLOR=#373737]структура программы с описанием функций составных частей и связи между ними" отлично ложится перечисление и описание компонентов, из которых состоит программа. Про сборку можно написать здесь же или в "общих сведениях" обозначить, как "программное обеспечение, необходимое для функционирование программы".
[/COLOR]
А ещё программы и методики испытаний в списке документов очень не хватает.
Яндекс организует конференцию для разработчиков документации 18 апреля
 
Я была на конференции в питерском офисе Яндекса. В целом - ничего сверхнового, но скучно не было. Да и просто пообщаться с коллегами - уже само по себе ценно.

Первые 3 доклада - как-то ни о чем, набор очевидных вещей или личный опыт, который у каждого свой. Доклад про сильный текст - слушать было интересно, хотя вроде ничего нового. Но с исправлением текста докладчик чуть переусердствовал - текст исчез, остались одни картинки. Основная польза - сайт, который он анонсировал, http://glvrd.ru/.

Про инструменты мне было бы интересно про опыт техписателей при работе с ними. В докладе про Author-it это было, про DITA - нет. С Author-it захотелось познакомиться поближе. Доклад про DITA получился каким-то антирекламным. Я вынесла из него примерно следующее: "Продукт сложный, для настройки и поддержки необходимо  привлекать сторонних специалистов. Мы несколько месяцев занимаемся внедрением, про результаты говорить пока рано. Но техписателям нужно убеждать начальство перейти на него, потому что опыт работы  с DITA - полезная строка в резюме техписателя."  
Сроки и время на разработку документации, Сроки и время на разработку документации
 
На этот вопрос невозможно ответить, слишком мало вводных.
Какие документы - эксплуатационные / проектные / весь комплект, начиная с ТЗ или отчета о предпроектном обследовании?
Указан ли стандарт, в соответствии с которым писать, и список документов в соответствии с этим стандартом?
Если в состав документации входят не только эксплуатационные документы, будет ли разрабатываться приложение в соответствии с ними или нужно писать их задним числом к уже созданной системе?
Будет ли заказчик читать, вникать в суть, предлагать поправки (и как быстро он это будет делать) или пробежит глазами на "соответствие ГОСТу" или вообще никто читать не будет, главное, чтобы был титульный лист с правильным названием документа?

И после ответов на все эти вопросы все равно не факт, что кто-то со стороны сможет оценить сроки. Но Вам самой станет лучше понятен масштаб проблемы.
Изменено: Марина - 03.04.2015 10:41:25
Обратное проектирование
 
В условии задачи не сказано, что документ пишется для программистов.
Обратное проектирование
 
Точно нужно настолько детальное описание программы, что необходимо погружаться в код на Java?

Разделы документа по ГОСТу:
[LIST][*]общие сведения;[*]функциональное назначение;[*]описание логической структуры;[*]используемые технические средства;[*]вызов и загрузка;[*]входные данные;[*]выходные данные.
[/LIST]Знание кода может потребоваться в одном пункте из 7 - "Описание логической структуры". А может и не потребоваться. Бывает достаточно написать, что программа состоит из таких-то модулей, каждый из которых отвечает за такую-то функциональность. Добавить схему взаимодействия этих модулей. Об этом должен иметь представление менеджер проекта или системный архитектор. И это можно рассказать, не зная языка, на котором эти модули реализованы.
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
[url=http://techwriters.ru/forum/user/13391/]ADVANCED[/url], резюмирую Ваши посты в этой теме.

Если техписатель пишет ТЗ, проектную документацию, маркетинговые материалы или методички, это на него навесили не его работу. Оформляет, редактирует, приводит к читаемому виду документацию, написанную программистами и аналитиками - тем более, почти приравнивается к мытью полов вместо уборщицы.

А вот настройка формы кнопок - его обязанность. Если ему это не нравится, он просто лентяй, который не хочет развиваться.
Изменено: Марина - 21.10.2014 15:59:53
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
[QUOTE]Виктор Фигурнов пишет:
[QUOTE] Марина пишет: А для написания технической документации их нужно знать на таком уровне?
[/QUOTE]Для написания может и нет, а для сдачи онлайн-документации заказчику очень может быть что да.

Заказчик говорит, что онлайн-документация ему в принципе нравится, но эта кнопочка должна быть с закругленными углами, этот ярлычок вкладки другой высоты, промежуток между панелями должен быть узкий, должны быть такие-то кнопки, которые то-то делают, и т. д. Будете отвечать, что ничего этого делать не умеете?
[/QUOTE]Если я - техписатель, знающий инструментарий на начальном уровне, говорю, что попробую разобраться, как это сделать, но возможно потребуется помощь и сроки надо сдвигать. Так в процессе работы и научусь.

Если я - менеджер, работающий с заказчиком, вежливо доношу до него мысль "любой каприз за ваши деньги". Пожелания про форму кнопок скорее всего сразу отвалятся. То, что действительно необходимо, будем осваивать, может быть, наняв верстальщика или оплачивая обучение верстке своих техписателей.  
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
Возвращаясь к теме. Тысячу раз имхо, прошу прощения, если кого-то обижу, но профессия "технический писатель" довольно узкая, в ней сложно как-то глубоко развиваться. И, главное, надо ли? Потолок по зарплате наступит довольно быстро, потолок в карьере - "начальник отдела документирования"? - очень редкая должность. Развивать навык написания понятных, читаемых текстов можно всю жизнь, но не обязательно в этой профессии.

Если хочется активного развития и роста, довольно быстро уйдёте в какую-то смежную область. Вот и выбирайте вначале область, куда хочется развиваться (технический переводчик, аналитик, верстальщик и т.д.), от этого и пляшите.
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
[QUOTE]Виктор Фигурнов пишет:
[QUOTE] techwriter пишет: HTML5 и CSS3 не те вещи, которыми имеет смысл хвалиться, т.к. в них чего-то мегасложного нет. Любой может научиться за месяц.
[/QUOTE]Ну попробуйте за месяц выучить HTML5 и CSS3, сдать экзамен и получить майкрософтовский сертификат "Programming in HTML5 with CSS3".

Тогда и будете говорить, что это несложно.
[/QUOTE]А для написания технической документации их нужно знать на таком уровне?
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
[QUOTE]ADVANCED пишет:
[QUOTE] techwriter пишет:
[QUOTE] ADVANCED пишет:
Вы зациклились на Ворде.
ТЗ необязательно писать в ворде, оно не обязательно должно быть распечатано на принтере. Оно не обязательно должно быть по ГОСТ и тд.
При упоминании ТЗ, почему-то ассоциация о печатном документе. Оно может быть в HTML и им пользуются разработчики как им удобно. Один на планшете, другой на компе, третьему достаточно прочитать.

Книги тоже не обязательно должны быть на бумаге. Есть e-book со своими форматами. И в них тоже можно писать и ТЗ и другую документацию и ГОСТ можно забыть.
[/QUOTE]Предложи свой вариант ТЗ так, чтобы при этом печатного и электронного документа не существовало в природе. При этом ТЗ содержало все обоснования решений, ограничения и условия.
[/QUOTE]Заказчик на встрече с аналитиком ставит требование "чтобы адрес можно было выбрать из списка". Аналитик отправляет программисту СМС "надо сделать справочник КЛАДР, подробности в письме". Пишет письмо в электричке пока не забыл, или прикладывает аудиозапись с диктофона. Когда аналитик приезжает на свое рабочее место со встречи, прикладывает переписку из почты в JIRA. Программист в это время уже заканчивает справочник и передает на тестирование. Тестировщик читает весь ход мыслей от появления идеи, до завершения разработки и тестирует, писатель документирует. Доработка сдается заказчику патчем или в следующем обновлении.
Вообще так редко бывает, если честно, но бывает. Пример из опыта работы с госзаказчиком. Срок разработки сокращен до минимума, все все выполнили, заказчик доволен. Никто не растягивает договоры, печати, ТЗ по ГОСТ и т.п.
[/QUOTE]
Вероятное развитие событий:

Все всё выполнили, но заказчик недоволен. Ему не нужен КЛАДР, а нужно чтобы в систему был забит его список адресов с пояснениями "пройти 10 метров от угла дома, свернуть в подворотню, постучать в дверь с красной вывеской 3 раза". Сейчас этот список написан нечитаемым подчерком в нескольких бумажных тетрадях. Те деньги, за которые компания готова за это взяться, заказчик платить не готов. Получили по половине человекодня программиста, тестировщика и техписателя, потраченных впустую, и недовольного заказчика. Этого можно было бы избежать, если бы аналитик не поленился перевести устное пожелание заказчика "хочу выбирать из списка" в требование "У пользователя должна быть возможность выбрать адрес из справочника КЛАДР" и отправить его на утверждение заказчику.  
На самом деле всё зависит от масштаба задач. Пожелание адекватного заказчика, которое может быть реализовано за полчаса, можно выполнить и без бюрократической волокиты. Но это именно выполнение мелкого пожелания, а не "разработка ТЗ без создания печатного или электронного документа".
Изменено: Марина - 07.10.2014 17:49:55
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
[QUOTE]ADVANCED пишет:
[QUOTE] Марина пишет:
"оформление документа в соответствии с заданным стандартом" - первый пункт трудовых функций. Не понятно, почему технический писатель не должен это делать или должен только на каких-то особых условиях.
[/QUOTE]Он может это делать если его попросят или если это его обязанность.

[/QUOTE]
Конечно, но это вполне естественная для него обязанность. Вы же выше писали, что это почти тоже самое, что заставить его мыть полы и заправлять кондиционер.
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
А я работаю, а не высиживаю. Разрабатываю программные продукты для энергетических объектов, нужные и востребованные. Просто развитие не меряю навороченностью инструментов и моделями айфонов.
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
Верю, что для большой распределенной команды и достаточно продвинутого заказчика это круто. Для небольшой команды, сидящей в одной комнате, с единственным аналитиком-техписателем, и заказчиками, использующими интернет только для чтения почты и новостей с рабочего компьютера, это не имеет смысла. Польза не окупит вложенных усилий.
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
http://www.apkit.ru/committees/education/meetings/standarts.php - здесь можно скачать проф. стандарт "Технический писатель (Специалист по технической документации в области ИТ)". Не понятно, принят ли он уже, но вряд ли есть что-то более новое на эту тему.

Там есть и разработка документов информационно-маркетингового назначения, и разработка документов уровня инженера или программиста. Просто для этого нужны более высокие уровни квалификации, чем для разработки пользовательской документации.

"Оформление и компоновка документов" - самый низкий уровень квалификации, "оформление документа в соответствии с заданным стандартом" - первый пункт трудовых функций. Не понятно, почему технический писатель не должен это делать или должен только на каких-то особых условиях.
Техническое задание (ТЗ), Обсуждаем как правильно составлять требования и разрабатывать техническое задание (ТЗ)
 
ТЗ в виде сайта, да ещё и красочного, делать не приходилось, потому что заказчикам не приходило в голову требовать. Когда-то делала юзабилити-аудиты интерфейсов, тоже никто не предъявлял каких-то особых требований к формам отчетов, всем хватало документа в ворде или pdf, конвертированного из ворда. С заказчиком обсуждались содержание и доступность изложения, форма - только в начале работы, с непосредственным начальством, на уровне "сделайте титульный лист по нашим корпоративным стандартам".

Разбить текст ТЗ на смысловые блоки, соответствующие вебстраницам, смогу без проблем. Сверстать каждую в HTML, наверно, тоже (но это ведь уже работа верстальщика)? Смогу внятно нарисовать прототипы карандашом на бумаге или в Visio (в Axura - это к проектировщику интерфейсов). Собрать из этого готовый сайт и разместить на хостинге - это к веб-программисту. Чтобы сайт был ещё и красочный - к веб-дизайнеру.
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
ТЗ могут писать аналитик, менеджер проекта, частично заказчик. Документы технического и рабочего проектов - программисты, системный архитектор. У них с грамотностью хуже, чем у аналитиков."Корова" через а не пишут, но забывают запятые, неправильно согласовывают деепричастные обороты. Пишут сложно и запутанно, так что сами не всегда потом понимают, что имели ввиду. Программу и методику испытаний вместе с аналитиком может писать тестер. Руководство пользователя - технический писатель. Кто-то должен привести все эти документы по одному проекту к единому виду - как минимум, чтобы терминология была сквозной. Кто этим должен заниматься?

http://techwriters.ru/forum/forum607/topic18101/ - тема с нашего форума про обязанности техписателя. Во всех примерах должностных инструкций присутствует "техническое редактирование научно-технических, информационных и нормативных материалов предприятия на русском и английском языках".
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
[QUOTE]ADVANCED пишет:
[QUOTE] Марина пишет:
У нас обычно под работой по 34 госту подразумевается разбиение проекта на этапы
1) техническое задание
2) технический проект
3) рабочая документация (2 и 3 часто объединяют)
4) ввод в действие
[/QUOTE] Если на то пошло, то писателю можно развиваться в направлении разработки проектной документации и расти к Системному или Бизнес-аналитику. Напомню, что ТЗ относится к проектной документации, а технический писатель может выступать в роли аналитика, только если есть знания, нывыки или желание. Но это не совсем правильно. [/QUOTE]
Я писала выше, я примерно туда и развиваюсь  :)  И должность у меня называется "аналитик", а фактически 2 в 1, тех. писатель + аналитик. Но там, где должности разделены, мне кажется, всё равно все документы должны проходить через тех. писателя. Общая грамотность текстов, единство стиля, оформление - это все его работа.

[QUOTE]ADVANCED пишет:
Есть пример красочного сайта технического задания по ГОСТ34?  :)  [/QUOTE]

Не поняла вопрос. Сайта, ТЗ к которому писалось по 34 госту?
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
Интересно, как по-разному можно толковать словосочетание "документация по 34 госту". В текстах 34 госта рамочки, по-моему, вообще не упоминаются. Есть ссылки на ЕСКД, ЕСПД и т.д., рамочки, наверно, оттуда. Я их видела на схемах и чертежах, которые готовили другие отделы или субподрядчики. С требованием сделать рамочки на текстовых документах ни разу за 3 года не сталкивалась. Настроить стили заголовков в ворде - минутное дело, это вообще глупо обсуждать.

У нас обычно под работой по 34 госту подразумевается разбиение проекта на этапы
1) техническое задание
2) технический проект
3) рабочая документация (2 и 3 часто объединяют)
4) ввод в действие

По каждому этапу должно быть написано один-два документа из списка http://standards.narod.ru/gosts/gost34/34-201-89.htm, их разделы и содержание должны быть как-то похожи на то, что написано в госте (обычно никто не сверяет, но если решат, что в документе не хватает чего-то важного, сошлются на гост). Для конечного пользователя из этих документов предназначено полтора, и никакой гост не запрещает кроме них сделать ещё и онлайн-хелп. Все эти документы читают не обязательно айтишники и "челы с шестыми айфонами". Инженеры старой закалки не меньше челов с айфонами заслуживают документации, подготовленной в удобном и привычном для них виде.
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
34 гост введен в действие в 90-х годах. Техническое задание отлично пишется по 34 госту, если использовать его в ситуации, для которой он и был предназначен - создание автоматизированной системы "под ключ", включая установку и настройку ПО на технике заказчика, возможно, поставку или апгрейд техники, обучение персонала.

Посмотрела сейчас на требования ГОСТ к руководству пользователя - не понятно, что там может быть бесполезным. По-моему, перечислен необходимый минимум того, что должно быть в документе. Гост не запрещает что-то добавлять или менять. Он вообще ничего не запрещает, а только предлагает  шаблоны, которые часто оказываются полезными и удобными.
Программа и методика испытаний
 
В дополнительные материалы ещё можно добавить гост 34.603-92 ВИДЫ ИСПЫТАНИЙ АВТОМАТИЗИРОВАННЫХ СИСТЕМ http://standards.narod.ru/gosts/gost34/34-603-92.htm
Технический писатель, направления для развития, Обсуждаем какие профессиональные направления развития есть у технического писателя
 
имхо любой инструмент хорошо осваивается в процессе работы над реальными задачами, для которых он подходит. Или, возможно, с наставником, который предлагает подходящие под инструмент задачи и оценивает результат. Изучать что-то в теории для строчки в резюме, по-моему, не очень осмысленно.

Для себя вижу развитие в изучении смежных областей - бизнес-анализ, анализ и проектирование интерфейсов, работа с требованиями. Ну и русский язык можно развивать до бесконечности - читать хорошую художественную литературу, переписывать свои или чужие тексты, делая их более понятными, обращаться к справочникам, если возникают сомнения, "как правильно это написать".
Есть-ли у кого-нибудь пример разработанного SRS
 
Вот, нашлось на компе. Откуда скачивала, не помню.
Ответственный исполнитель, Как вы называете исполнителей работы
 
"Ответственный исполнитель" - это устоявшийся термин. Есть проект, по нему один из нескольких "равноответственных" специалистов назначается ответственным исполнителем. Он отвечает за своевременность выполнения работ, согласование изменений, полноту документации, её своевременную отправку и т.д. За содержание работ может отвечать полностью, может частично, в зависимости от квалификации и внутренних правил компании.  Если требуют в этих терминах, значит они их используют в работе. Нужно подробнее выяснять, как у них построены завязанные на это бизнеспроцессы, и описывать в документе.
Обсуждаем санкции против России!
 
А очевидно всем разное :)

Во-первых, что считать началом - санкции ЕС, начало войны на юго-востоке Украины, аннексию Крыма, Майдан в Киеве (какой из), развал СССР, холодную войну...
Про каждое из этих начал можно спорить, кто там прав и по каким критериям это определять. Но честно говоря лень.
Страницы: 1 2 След.

Рейтинг@Mail.ru