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

Вот здесь наши  "[URL=https://techwriters.ru/learning/distantsionnye-kursy/]Курсы для технических писателей[/URL]"

на 11 мая 2022 все официально

Вопрос из нашего телеграм-канала

[I]всем привет, кто-нибудь может подсказать насчет кодировки в Help&Manual 7? У меня из-за нее поиск по ходу сломался в конечных PDFках....[/I]

Кто может подсказать?

[QUOTE]Виктор Фигурнов написал:
Кажется, что SPHINX и AsciiDoctor (или AsciiDoc) это не системы автогенерации документации из кода.

А просто системы подготовки документации. Первая основана на языке упрощенной разметки RST, вторая на собственном языке, некоем "языком упрощенной разметки на стероидах".[/QUOTE]
Да, все верно, перенес в эту тему [URL=https://techwriters.ru/forum/forum604/topic21584/]https://techwriters.ru/forum/forum604/topic21584/[/URL]. Спасибо

Список инструментов
[LIST]
[*]SPHINX (отличная дока для старта [URL=https://sphinx-ru.readthedocs.io/ru/latest/index.html]https://sphinx-ru.readthedocs.io/ru/latest/index.html[/URL])
[*]AsciiDoctor
[*]Foliant (в разработке, но много интересного сделано)
[/LIST]

Изучите подобную документацию у конкурентов, все непонятные вопросы выясняются у разработчиков. Как правило пишешь сам, как понимаешь , потом отдаешь разработчикам на вычитку, потом правки

Ася написало все правильно)

Круто! Есть перспективы на работу по Docs as code?

Обсуждаем работу по созданию документации в Sphinx и настройку шаблонов по ГОСТ 19 и  ГОСТ 34

[QUOTE]DmitriyL написал:
Здравствуйте! Хочу научиться создавать chm-документы с оформлением как здесь:  [URL=https://ibb.co/80w7B2B]скрин[/URL] [URL=https://ibb.co/80w7B2B]_01[/URL]

Какие элементы не получается оформить по образцу:  [URL=https://ibb.co/99KKk8W]скрин_02[/URL]

Напишите, пожалуйста, как привести документ к желаемому виду. Программа используется версии 7.5.3 с Premium Pack 2.72

Сами файлы проекта (если кому требуется для экспериментов) залил  [URL=https://www.sendspace.com/file/79ecs5]сюда[/URL] [/QUOTE]
Вам нужно копать css стили вашего шаблона, там прописать как будут выглядеть ссылки и где будет расположен логотип и т.д.

Ответ с нашей группы в телеграмм от 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
[*]NATURAL DOCS
[*]DocFX ([URL=https://dotnet.github.io/docfx/]https://dotnet.github.io/docfx/[/URL])
[/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]

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

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

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

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

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

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

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

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

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