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

Ответ с нашей группы в телеграмм от Olga/E:

пишите требования к способам, методам исследований. к исследуемым моделям, алгоритмам и пр.

Коллеги, есть у нас такой тонкий лед в ПМИ: в рамках работы текст программы должен быть приведен в соответствие с требованиями:
- открытой лицензии Apache software license 2.0; Как это требование проверить? Открыть лицензию, открыть код, проверить соответствие? Кто-то что-то подобное описывал?

Буду по мере поступления предложений актуализировать список, пока он такой:
[LIST]
[*]Swagger ([URL=https://swagger.io/]https://swagger.io/[/URL])
[*]Javadoc ([URL=https://www.oracle.com/java/technologies/javase/javadoc.html]https://www.oracle.com/java/technologies/javase/javadoc.html[/URL])— генератор документации в HTML-формате из комментариев исходного кода на Java от Sun Microsystems. Javadoc — стандарт для документирования классов Java. Большинство сред разработки программного обеспечения автоматически генерируют HTML-документацию, используя Javadoc.
[*]DOXYGEN
[*][B]SPHINX[/B] (отличная дока для старта [URL=https://sphinx-ru.readthedocs.io/ru/latest/index.html]https://sphinx-ru.readthedocs.io/ru/latest/index.html[/URL])
[*]NATURAL DOCS
[*]DocFX ([URL=https://dotnet.github.io/docfx/]https://dotnet.github.io/docfx/[/URL])
[*][B]Foliant[/B]
[*][B]AsciiDoctor[/B]
[/LIST]

Коллеги, делаем большой проект на опенсорс. Сейчас рассматриваем варианты и возможности автогенерации документации из кода. Какие технологии и инструменты сейчас актуальны?

Интересно))

[QUOTE]Iriska написал:
Здравствуйте.
После собеседования дали тестовое задание написать инструкцию по завариванию чая.
Не конкретизировали в какой форме она должна быть написана.
Подскажите пожалуйста написать в произвольной форме или на основании ГОСТ?[/QUOTE]
Пишите по ГОСТ, интересней будет)

Может в отображении просмотрщика pdf не настроено? А другие документы отображаются?

Еще уточню по ЧТЗ для госзаказчика. Что они имеют ввиду) Для них ЧТЗ, это по факту Уточненное техническое задание. т.е вам нужно ТЗ к договору  расписать более подробно. Копируйте структуру и вперед. Не все разделы копируйте, можете просто ссылаться на них из ЧТЗ.
В аннотации к документу можно уточнить про это примерно так:
[QUOTE]В документе приняты следующие допущения: положения ТЗ, по которым обязательства детализации таковых в ЧТЗ прямо не предусмотрены (договором, контрактом, от такого-то числа) и/или по своей сути не требуют дополнительных уточнений в рамках ЧТЗ, представлены в форме согласия с объемом требований ТЗ, в том числе в форме типовых утверждений «Содержание данного подраздела соответствует содержанию подраздела Х.Х ТЗ».[/QUOTE]

Полезная ссылка: [URL=https://techwriters.ru/articles/razrabotka-tekhnicheskoy-dokumentatsii/dokumentirovanie-v-razrabotke-po/]https://techwriters.ru/articles/razrabotka-tekhnicheskoy-dokumentatsii/dokumentirovanie-v-razrabotke-po/[/URL]

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

Мы обходим это тем, что более подробно описываем функционал, например, есть в ТЗ пункт "Создать ЛК администратора", то в ЧТЗ максимально подробно описываем информацию по каждой функции ЛК, прототипы макетов экрана,Use Case.
Например, ЛК; содержит следующий функционал:"Список пользователей системы". В котором необходимо реализовать следующее: Просмотр списка пользователя с помощью кнопки "Все пользователи". "Добавление пользователя".  Добавить пользователя с помощью кнопки "Добавить пользователя", с вызовом карточки "Добавить пользователя" содержащий следующие поля: ФИО, E-mail" и номер телефона. Сохранения карточки с помощью кнопки "Сохранить". Отменить сохранение с помощью кнопки "Отмена".

Коллеги, как вы обходите требования тендеров (госзакупок) о том, что обязательно должно быть ЧТЗ? По факту ведь ЧТЗ это на часть системы разрабатывается, а если например, полностью разрабатывается система и требование разработать ЧТЗ это какой-то бред. По факту получается дубляж ТЗ. Что думаете?

Вот еще важный момент:
ЧТЗ  в том же ГОСТе 34.602-89 пункт 2.2[QUOTE]В ТЗ на части системы не включают разделы, дублирующие содержание разделов ТЗ на АС в целом.[/QUOTE]

Как относятся у вас к такой формулировке. Сплошь и рядом вижу, что ЧТЗ это клон ТЗ со всеми разделами, а по факту  в частное техническое задание (ЧТЗ) нужно включать только те разделы, которые уточняют требования к конкретной подсистеме, на которую и разрабатывается ЧТЗ.

В случае, если система большая, разумно сделать Частные технические задания на каждую подсистему.
ЧТЗ должны содержать:
• ссылку на пункт ТЗ;
• максимально подробную информацию по каждой функции;
• список UseCases для функции.
Таким образом реализуется преемственность документов, что позволяет, во-первых, унифицировать их форму, во-вторых – частично реализовать повторное использование, то есть снизить затраты времени на «писанину».
Например, мы формируем ЧТЗ на всё ту же подсистему «Администрирование». Оно будет содержать описание функции: «Создание карточки. Необходимо реализовать следующий функционал: вызов карточки посредством кнопки «Создать», интерфейс карточки, содержащий следующий набор полей, сохранение карточки посредством кнопки «Сохранить», отмену сохранения посредством кнопки «Отмена»».

[B]Новый ГОСТ на разработку Технического предложения ГОСТ 2.118-2013
[/B]
Настоящий стандарт устанавливает общие положения по выполнению технического предложения на изделия всех отраслей промышленности.

Обратите внимание!
ТП является первоначальной стадией разработки КД по ГОСТ 2.103 -2013. [B]Разрабатывать Техническое предложение его следует в соответствии с ТЗ (!!!)[/B], с целью технического и технико-экономического обоснования целесообразности разработки КД изделия, на основании анализа различных вариантов возможных решений изделий, сравнительной оценки решений с учетом конструктивных и эксплуатационных особенностей разрабатываемого и существующих изделий, а также с целью выявления дополнительных или уточненных требований к изделию (технических характеристик, показателей качества и др.), которые не могли быть указаны в ТЗ. Это целесообразно сделать на основе предварительной конструкторской проработки и анализа различных вариантов изделия.

Примечание - ТП не распространяется на КД изделий, разрабатываемых по заказу Министерства обороны.[B]
[/B]

[CENTER]ГОСТ на оформление Технического предложения
ГОСТ 2.118-73 ЕСКД. Техническое предложение

ПЕРЕЧЕНЬ РАБОТ, ВЫПОЛНЯЕМЫХ НА СТАДИИ ТЕХНИЧЕСКОГО ПРЕДЛОЖЕНИЯ[/CENTER]

В общем случае при разработке технического предложения проводят следующие работы:

а) выявление вариантов возможных решений, установление особенностей вариантов (принципов действия, размещения функциональных составных частей и т.п.), их конструкторскую проработку. Глубина такой проработки должна быть достаточной для сравнительной оценки рассматриваемых вариантов;

б) проверку вариантов на патентную чистоту и конкурентоспособность, оформление заявок на изобретения:

в) проверку соответствия вариантов требованиям техники безопасности и производственной санитарии;

г) сравнительную оценку рассматриваемых вариантов. Сравнение проводится по показателям качества изделия, например, надежности, эко номическим, эстетическим, эргономическим. Сопоставление вариантов может проводиться также по показателям технологичности (ориентировочной удельной трудоемкости изготовления, ориент ировочной удельной материалоемкости и др.), стандартизации и унификации. При этом следует учитывать конструктивные и эксплуатационные особенности разрабатываемого и существующих изделий, тенденции и перспективы развития отечественной и зарубежной техники в данной области, вопросы метрологического обеспечения разрабатываемого изделия (возможности выбора методов и средств измерения) .

Если для сравнительной оценки необходимо проверить принцип рабо ты различных вариантов изделия, а также сравнить их по эргономическим и эстетическим показателям, то могут быть и зготовлены материальные и (или) разработаны электронные макеты;

д) выбор оптимального варианта (вариантов) изделия, обоснование выбора; установление требований к изделию (технических характеристик, показателей качества и др.) и к последующей стадии разработки и зделия (необходимые работы, варианты возможных решений, которые следует рассмотреть на последующей стадии и др.) ;

е) подготовку предложений по разработке стандартов (пересмотр или внесение изменений в действующие стандарты) , предусмотренных техническим заданием на данной стадии.

ж) проработку вопросов, обеспечивающих возможность использования конструкторской документации в электронной форме на последующих стадиях разработки

Всем привет! Поступила мне такая задача: разработать документ "Техническое предложение" на автоматизированную систему (АСУ). Это, достаточно, популярная задача для технических писателей. Решил создать тему, где можно все это обсудить и решить что для этого нужно, с чего начать, какие документы пригодятся.
Собираем все вопросы по этой теме здесь

какого плана нужна помощь? Написать или подсказать как писать?

Что-то не совсем туда написали

я тоже немного в шоке от таких требований))

Там описываются проведенные исследования на патентную чистоту. По конкурентноспособности, можете привести 2-3 программы похожего направления и сравнить, чем ваша программа (АСУ) лучше.

Подсказали в нашей группе : изменяются настройки по умолчанию

Коллеги, нам задавали вопрос (автор AGL, надеюсь он не против что мы восстановили вопрос) по опыту интеграцииHelp&Manual + SVN+ Subversion (опыт интеграции). $nj что может подсказать? Вопрос интересный, цитирую автора:

"Поддерживаю документацию для разрабатываемого нами ПО - 3 типа руководства на русском языке и 3 их аналога на английском языке. Хотя общая структура документов близка, оформление на английском языке отличается, поэтому можно говорить про 6 различных проектов. Готовые документы
сохраняются в SVN на сервере, с которой работают программисты, после чего происходит сборка.

 Чтобы упорядочить процесс создания документации, я локально установил Subversion сервер, Tortoise клиент и версионировал свои исходные файлы, из которых произвожу сборку PDF файлов на выходе. Я преследовал цели резервирования файлов, отслеживания внесенных изменений в журнале. Достигнутый
результат меня удовлетворяет.
 Репозиторий один, он содержит 6 проектов в папках поименованных по названию документов:(IMAGE: [URL=https://fotohosting.su/images/2019/07/22/KRANILISE.png]https://fotohosting.su/images/2019/07/22/KRANILISE.png[/URL]) (URL: [URL=https://fotohosting.su/images/2019/07/22/KRANILISE.png]https://fotohosting.su/images/2019/07/22/KRANILISE.png[/URL] )
 Стволовые файлы хранятся в директориях trunk. Планировал в директориях branches работать в процессе подготовки релизов ПО, а состояние документации на моменты релизов сохранять в директориях tags.

 Скажем, для версии 6 документация пишется в течение года, пока идет разработка и сертификация ПО, и процесс улучшения документов перманентный в свете исправления ошибок и обратной связи технической поддержки с клиентами. В то же время идет разработка 7 версии, которая существенно
отличается от 6 версии.
 Функционал описанный в документации 6 версии, должен быть описан и в 7 версии. Но отдельные исправления могут быть осуществлены только в 7 версии, а в 6 версии должны быть описаны костыли, помогающие выжить.


Вопрос.

 Можно ли организовать версионирование так, чтобы рабочие версии 7 сформировались на основе версии 6, а дальнейшая работа проходила независимо с версией 6 и версией 7, но при исправлении в 6 версии ошибок, характерных обеим версиям, существовала возможность простого слияния и только
в рамках конкретной ошибки (ничего лишнего)?"

Привет!
Если еще актуально, волт такие предложения были в нашем @twriters чат для технических писателей в Telegram:

1. При помощи фотоаппарата, перекачивать по USB и обрабатывать
   
2. Я ставлю эмулятор мобильной ОС. И снимаю скрины обычными средствами типа SnagIT и т.д. По-моему - самый удобный и эффективный вариант
   

Вставка html-кода скорее всего может пригодится для вставки видео, картинки с сервера, вставки frame и т.д.