Комментарии 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). — перечисление объектов языка, описание библиотек.
Иногда очень не хватает первых двух руководств. Одного справочного руководства недостаточно.
Инструкции к приборам имеют те же недостатки. Обычно, в них описывается всё по принципу "если вы хотите сделать вот это, то проделайте следующие операции". А нужно, сначала, узнать, а что вообще можно сделать с помощью данного прибора. В начале каждой инструкции должен быть текст с перечислением всех рабочих функций. И далее в том же духе.
Зачем нужны технические писатели