Pull to refresh

Comments 18

Спасибо, с интересом почитаю!


Будут ли затронуты форматы (word, latex, md и т.д.), и оформление (секции, ссылки, таблицы и т.д.)?

спасибо за интерес) можно затронуть форматы и тулзы, да, беру на заметку)

А где статья? Плюсанул только чтобы автор сделал продолжение, но надеюсь оно будет пополнее.
Поделись опытом, друг, походу он у тебя интересный.

Документация по ГОСТу нужна чтобы любой человек со стороны смог воспользоваться вашим изделием(ПО) и не было никаких разночтений. После того как вы ее напишете — она отдается на испытания гомодрилам, которые впервые видят это ваше изделие(ПО). И если они не смогут выполнить все что написано в инструкции — то ваше изделие(ПО) не работает.
Современное ПО общего назначения — к нему нет таких требований. Да и если у вас чтото не будет получаться — это даже лучше — пойдете на курсы или воспользуетесь поддержкой. По этой причине документация для современного ПО общего назначения вообще лишнее.
ну как же нет требований? есть, конечно. требования по функционалу пишутся менеджером продукта, потом при тестировании используются так же, как и требования по ГОСТу. только они пишутся по-другому, но суть та же.
в моих статьях я буду больше говорить про руководства пользователей, то, что в ГОСТах или ЕСКД называется РО, РЭ, или РТЭ. в таких документах как раз нужно ориентироваться на пользователя, и в этом они схожи с user guides в привычном понимании этого слова.
К современному ПО общего назначения нет требований чтобы абсотютно любой человек смог им воспользоваться и все его функции были описаны максимально точно. Пользовательской документации к блокноту, проводнику, браузеру я не видел.

Требования по функционалу — это не пользовательская документация. Это один из видов того, как будет ставиться задача по разработке ПО. Каждая организация сама решает какую модель разработки ПО она будет использовать, в каком виде будет ставиться задача (напишут техническое задание по ГОСТу, напишут технические требования в ворде или накидают задачи в Trello или Jira).

Что такое РЭ? Если это «Руководство по эксплуатации» — то это документ ЕСКД. Если вы пишите документацию по ГОСТу для ПО, то нужно использовать не ЕСКД (ГОСТ 2.ххх), а ЕСПД (ГОСТ 19.ххх). РЭ — не пишут для ПО. Все виды программных документов по ЕСПД указаны в ГОСТ 19.101-77.

Вот вы пишете «в международных компаниях пишут по style guides (Microsoft Manual of Style, например).… Здесь фокус смещен с продукта на читателя.»
Откроем например документ "Installing PowerShell on Windows":
Там написано:
The MSI file looks like PowerShell--win-<os-arch>.msi. For example:

PowerShell-7.1.0-win-x64.msi
PowerShell-7.1.0-win-x86.msi

Once downloaded, double-click the installer and follow the prompts.

The installer creates a shortcut in the Windows Start Menu.

Здесь они тоже все пишут абсотютно так, как вы пишете в колонке «Конструкторский подход». Все описано максимально подробно как должен быть именован файл, и что его надо запускать двойным кликом.
спасибо за развернутый ответ!
про блокнот, проводник, браузер я не знаю. но с нашим продуктом мы стремимся к тому, чтобы наш юзер смог воспользоваться ПО, и все его функции были описаны максимально точно для целей пользователя. То есть юзер найдет точное описание, как ему что-то сделать. Но это не то же самое, как если мы опишем точно и полностью, как там на бэкенде продукт работает. Насколько это обязательное требование? В тех же style guides, на которые мы ориентируемся, оно есть. Вот можете посмотреть, и даже покритиковать наши документы, а мы их постараемся улучшить) www.acronis.com/en-us/support/documentation
насчет того, что даже в MS, у которых, на мой взгляд, лучший style guide, не все доки один к одному по нему написаны, я согласна. мой опыт мне подсказывает, что все доки надо улучшать, улучшать, улучшать, и ни конца ни края не видно этому. я думаю, здесь главное — стремиться, работать над этим, и точно доки становятся лучше, чем были. хотя до совершенства далеко)
и вот еще интересный момент, по поводу того, что «абсотютно любой человек смог им воспользоваться», тут есть нюансы. у любого продукта есть целевая аудитория, вот ее представители должны понять, согласна. но если человек не шарит в серверах, то документы на Acronis Cyber Infrastructure ему будет сложно понять, он не попадает в целевую аудиторию — сисадмины. и это нормально. документация изначально рассчитана не на всех.
а по поводу ЕСКД/ЕСПД, руководство по эксплуатации можно улучшить, независимо от того, описывает ли оно ПО или какой-нибудь чудесный блок, железку)
Проблема не в том, что технические писатели пишут не для пользователя, а в том, есть, помимо ГОСТов, различные РД, например Транснефти, которые диктуют как именно писать. И как-то по другому, более понятно для пользователя, составить они не могут из-за формальностей, а не потому, что не хотят.

Плюс есть большая разница между ЕСКД и ЕСПД для текстовых документов. И вот как раз ЕСПД уже морально устарел, так как большинство информации в нём осталась из 80-х.
очень интересно! мне не попадались РД для русских документов. Были руководства корпоративные, но они скорее по стилю оформления. Ну или ГОСТы, но это не совсем то, да? Расскажие, пожалуйста, поподробнее! РД — это «руководящий документ»? А там есть какие-то требования к текстам, или прописана целевая аудитория? А что там такого написано, что не дает документы улучшать?
Гостов-то навалом, начиная с 2.105 по оформлению и заканчивая гостом на каждый отдельный документ, типа техзадания, РЭ, РО, отчета о НИР и тому подобного. В ЕСПД (ГОСТЫ 19 серии) есть указания по содержанию некоторых программных документов, хотя это изрядно устарело. РД на предприятиях старого типа обычно называются стандартом предприятия (СТП) или стандартом организации (СТО) и обычно содержат изрядный кусок соответствующего госта с уточнениями и примерами применительно к конкретному производству/разработке. В организациях попроще и стандарты попроще, обычно устанавливаются требованиями заказчика.

А написано там примерно то же, что и в ГОСТ. Например, «Инструкция по настройке должна содержать следующие главы:» и задолбаешься доказывать в ОНС, что тебе 3 главы из этих не нужны ваащще, зато надо обязательно добавить 2 не упомянутые… А за соблюдением стандартов следит этот самый отдел нормалей и стандартов, без визы которого не подпишут «Утверждаю».
понятно, спасибо. на моей практике аналогичный отдел в доках больше смотрел на оглавление, чтобы все пункты были как в гостах. а к формулировкам особо не придирались.
Щелчком ПКМ нажмите на значок файла на рабочем столе. В открывшемся меню выберите «Копировать». Затем в проводнике откройте папку, в которую вы хотите скопировать файл. Щелчком ПКМ откройте выпадающее меню и выберите «Вставить».
У вас нет отдела нормалей и стандартов? Счастливый человек… У меня этот пункт выглядел примерно так:
Наведите указатель в виде стрелки на рабочем столе на символ файла в виде изображения лупы и однократно кратковременно нажмите на левую кнопку манипулятора «мышь». В появившемся ниспадающем меню наведите указатель в виде стрелки на пятую снизу строку с надписью «Копировать»и ...
ну, и далее по тексту. А потом спорить, что лучше написать «Копировать», а не КОПИРОВАТЬ, в зависимости от того, как трактовать ГОСТ 2.105
бомбический пример, спасибо!
самое интересное, что иногда такой стиль используется по умолчанию даже в тех документах и конторах, которые уже не привязаны к стандартам и имеют полное право писать по-другому. такая светлая, добрая традиция.
Тут палка о двух концах.

С одной стороны такой безумный стиль имеет вполне оправданные причины. Наши тетеньки из ОНС требуют, чтобы документ был написан так, чтоб они поняли. В результате получается бумага, которую можно передать не только коллеге (который если что может подойти и переспросить непонятное), но и на другое предприятие другого города. Да и другой страны, потому что такой стиль довольно легко переводить. Вы бы видели РЭ на авиационную технику… Элементарные действия на 3 строчки на отдельных листах каждое. Формулировки такие, что вчерашний призывник из глухого села или интерната для альтернативно одаренных справится, если хотя бы по слогам читать умеет.

Но с другой стороны в результате на простой документ уходит раз в 5 больше времени и бумаги, потому что элементарные вещи приходится расписывать как для слабоумного. Иногда я срываюсь и начинаю воевать — доказывать, что в начале документа написано русским по белому — инструкция предназначена для настройщика категории не ниже 4, ознакомившегося с ТУ и принципами работы прибора. Защититесь на 4 категорию, почитайте ТУ, потом поговорим, что вам непонятно. Иногда помогает… А иногда приходится писать для себя и для своих отдельный неофициальный «документ», которым потом все реально и пользуются.
Ирония судьбы. Я не просто видела РЭ на авиационную технику, я с ними работала, и долго)
тетеньки из ОНС не правы, что тут скажешь)
Лайфхак: при переводе такого дикого текста на английский и французский, на выходе получаешь просто нечитабельные тексты, от слова «совсем». Но мы где-то в гостах нашли, что переведеннная документация должна отвечать международным стандартам. А там уже повеселее, там и ЦА, и понятность, в-общем, доки получаются получше. Так формулировки на других языках у нас были лучше, чем на русском.
Щелчком ЛКМ манипулятора типа «мышь» нажмите на значок папки.

Это выдуманный пример или настоящий? Потому что буква «М» в слове ЛКМ уже означает «мышь».
это то, как я помню те документы, с которыми работала. сейчас посмотрела в одном старом документе, точно такого не нашла, но близко: «С помощью манипулятора «мышь» установите курсор на указанный пункт меню и щелкните по нему 1 раз ЛКМ. В результате выполненной команды на экране откроется окно».
Sign up to leave a comment.