Комментарии 25
TL;DR.
Программисту ж вывод статьи совсем просто объяснить: спросить, готов ли он выполнять работу технического писателя вместо своей.
Вот признаки плохого интерфейса, которые сразу видны техническому писателю:
объекты с непонятным назначением, с неочевидным названием или вовсе без названия;
неочевидные и скрытые возможности интерфейса, о которых пользователь не может узнать без чтения документации;
большое количество кнопок с непонятными пиктограммами, без описания и всплывающих подсказок.
Простите, вы последний раз, когда шелл видели? Неочевидных возможностей...
man console_codes|wc -l
547
man bash|wc -l
6418
man readline|wc -l
1125
man pty|wc -l
58
man pts|wc -l
35
И ничего так, живут. Без всплывающих подсказок и с неочевидными ^C иконками.
man это документация, написанная технарями для технарей. Документация здорового человека это совсем другой литературный жанр.
Да, я видел. К кофе-машине (весом 11 кг) прилагалось 7 томов документации, весом примерно 5 кг (и я доставку этой маккулатуры оплачивал). Это была ОЧЕНЬ полезная документация, в которой первые пять страниц были посвящены условным обозначениям, следующие 10 - электрической безопасности и предупреждению о том, что горячая вода горячая, а полиэтиленовые пакеты не игрушка для детей, потом примерно 50 листов банальностей "нажмите кнопку эспрессо с иконой эспрессо для получения эспрессо", потом полторы страницы важного (настройка уровней и температуры), а потом длинный troubleshooting guide, сводящийся к "включите и выключите" и "звоните в сервис-центр". А потом то же самое на всех языках юникода снова и снова.
Я бы предпочёл man coffe-machine
.
предупреждению о том, что горячая вода горячая, а полиэтиленовые пакеты не игрушка для детей
Помню инструкцию читал, к кухонному комбайну, там написано: «не ложите руки во включенный блендер, это может привести к травме.» Интересно, взрослый человек в трезвом состоянии, разве будет так делать?
Не будет ли попытка поставить на первое место (по времени) технического писателя вариантом литературного программирования, когда программист берётся за дело только после того, когда создаваемая система уже описана в полном и понятном виде?
Это всё розовые мечты, примерно как писать программу по готовому ТЗ, которое не меняется по ходу дела.
Литературное программирование это когда программист преимущественно рассуждает и излагает решение задачи на естественном языке, лишь периодически опускаясь до языка программирования, чтобы перевести свою мысль компьютеру? Мне кажется это было популярно пару десятков лет тому назад, в эпоху мейкфайлов, TeX и Perl - где неподготовленному человеку смотреть на код было страшновато. Современные языки программирования подталкивают сразу писать так, чтобы код содержал привычные слова.
У меня был опыт создания изделий по пользовательской документации (охранные системы). Начальник отдела писал документацию так, как будто изделие уже существует. Потом приносил программистам, и спрашивал, нет ли в ней какой то очевидной фигни. В процессе разработки, если попадались какие то сложности, документация корректировалась (не сильно).
Это была работа мечты :-).
Скорее, BDD. Уже придумана и используется.
В нашей реальности техписы особенно нужны, чтобы оформить документацию для приемки работ по госконтракту. Потому что у программистов точно не хватит терпения описывать этим жутким канцелярским языком работу своего приложения.
Для госконтрактов техпис не нужен, берешь ТЗ и для каждого пункта пишешь какие действия приведут к описанному в ТЗ результату На выходе получается говно которое вполне устраивает всех участников этого противоестественного процесса.
Это может сделать и макака, однажды такой макакой был я, единственная сложность - не сойти с ума.
Техпис не нужен потому что читать это будут только на приёмке и только с целью поиска не соответствия с ТЗ. Тратить время специалиста на такую работу это унижение специалиста. А если он выпустит нормальную документацию а проверяющий по ней не сможет понять что заявленная фукциональность выполняется - будут проблемы, и аргумент "ваш проверяющий тупой" будет крыться аргументом "документация предназначена для людей с общим образованием".
Всё-таки, интересно, что будет, если заставить программиста сначала описать "жутким канцелярским языком работу своего приложения", а, уже потом, сделать само приложение?
Интересно, как вообще люди попадают в эту профессию и где потом тусуются? Есть-ли какое-то специальное образование, или может быть достойные курсы?
Скажу как технический писатель, правда, не совсем такого профиля, как описан в статье (пишу только на английском, в прошлом доку к библиотеке компонентов интерфейса, сейчас документирую уже SaaS):
Курсов как у программистов толковых нет от слова совсем, даже на курсере и Джеми предлагают какую-то дичь. Люди в профессию попадают с технических отделений вузов, когда понимают, что им не слишком сильно нравится программировать но они уже понимают, зачем нужна документация. Второй вариант (мой) - лингвистический факультет за плечами, но интерес к программированию в широком смысле и какой-то учебный бекграунд. Иногда также видел людей из саппорта, они хорошо понимают, как дока решает задачи пользователей.
Есть такие люди, которым скучно просто заниматься железками или программами
Вот что-то не верится, что если человеку скучно разрабатывать и программировать, то весело писать нудные тексты.
На флирансе наблюдаю тенденцию вымирания технических писателей. Все больше теоретиков, которым платят за информацию о том, что снег белый и он может выпасть, для мест где его не бывает круглый год.
Раньше использовалось следующее естественное разделение документации на:
Руководство пользователя (Users guide). — Собственно, что можно сделать, как пользоваться.
Руководство программиста (Programmer's guide). — Как писать программы на данном языке программирования и с данной среде разработки.
Справочное руководство (Reference guide). — перечисление объектов языка, описание библиотек.
Иногда очень не хватает первых двух руководств. Одного справочного руководства недостаточно.
Инструкции к приборам имеют те же недостатки. Обычно, в них описывается всё по принципу "если вы хотите сделать вот это, то проделайте следующие операции". А нужно, сначала, узнать, а что вообще можно сделать с помощью данного прибора. В начале каждой инструкции должен быть текст с перечислением всех рабочих функций. И далее в том же духе.
Зачем нужны технические писатели