О техническом писательстве
Пишу доку к варезу, первый раз за много лет - для обычного пользователя, сферического в вакууме (все что писал в последние годы - было доками по библиотекам т.е. для программистов).
Нашел в самой задаче крупное логическое противоречие:
- С одной стороны: загружать разработчика такой работой - противоречит самой идее разделения труда. Архитекторы должны архитектить, кодеры - кодить, тестеры - тестить, технические писатели - писать мануалы, а специалисты по пуговицам - пришивать пуговицы.
- С другой стороны: технический писатель имеет дело с черным ящиком. Он не знает что там внутри, если в программе вдруг что-то нелогично, то не его (писательское) дело против этого протестовать. Ему что дали - про то он и споет.
У разработчика же глаз замылен - ему в процессе работы весь этот варез уже опротивел, он если добавил новую фичу (сам или архитектор ему наархитектил), то протестирует только ее (в лучшем случае, а в худшем - не тестируя отдаст тестеру), а как она вписывается в общую конструкцию - смотреть не будет т.к. в другие места программы в процессе разработки не полезет.
А вот пиша (писуя?) документацию - до всех потаенных углов долезешь и все нелогичности внезапно увидишь. У меня список мелких багов образовался за время писания - больший, чем за предыдущие месяц-два.
Comments
IMHO: доку надо писать в два
IMHO: доку надо писать в два этапа. На первом этапе разраб документирует и сам все нелогичности вылавливает, на втором этапе тех. писатель переводит документацию на человеческий язык.
Не вполне про софт, а про
Не вполне про юзерский софт, а про библиотеки. В библиотеках это кончается тем что
- документация генерируется автоматом, через Doxygen
- никто ее не правит, ибо править результаты работы автомата бессмысленно, править надо исходник, а кто туда пустит техписателя.
- полезность документации в единицах полезности на килобайт уверенно стремится к нулю.
ну тут вопрос кто чего хочет
ну тут вопрос кто чего хочет опять-таки ...
у нас вот техписы регулярно делают ревью тех же строк локали, и вообще сообщений и т.д., и есть процесс их правки ...
Локаль-сообщения - это
Локаль-сообщения - это понятно, но мелко.
У меня вот, например, "нарушилась связь времен" - т.е. утерялось обновление данных в одной дырочке при изменении параметров в другой.
Внешний писатель не имеет шансов это заметить, не то что внятно рассказать.
ну ты ж сам пишешь про
ну ты ж сам пишешь про автодокументацию - такое техпис может найти вполне и баг забить :)
про нарушения самого апи - ну тут оппаньки, только юнит тестами и прочими тестами ...
- документация генерируется
- документация генерируется автоматом, через Doxygen
Это должна быть тока для техписа, а не конечная. Ессна, надо смотреть дифы для синхронизации.
Править руками результаты
Править руками результаты компиляции (Doxygen) - это как править руками (со всеми диффами и т.п.) ассемблер после компилятора.
Можно, но по сути - издевательство.
Знакомые техписы говорят, что
Знакомые техписы говорят, что очень плохо, когда это чёрный ящик и техпис не имеет права на обратную связь.
Что хороший техпис должен иметь разработчиков в мозг по поводу нелогичностей, которые приходится описывать, а процесс (начальство, etc.) должно ему это позволять -- как тестеру надо иметь право репортить технические баги.
Ну, и да, не забываем про модное нынче слово юзабилити-тестирование.
У тестеров это обратная связь
У тестеров это обратная связь подразумевается изначально, иначе зачем все это.
У писателей - подразумевается не всегда. Но так - я согласен, конечно нужна обратная связь.
Но при этом надо отдавать себе отчет, что время реакции в сколько-нибудь большом коллективе будет не две минуты, а скорее две недели. Отчего процесс сходиться будет медленно, а оверхеду будет вагон.
время реакции в
Мне кажется, это не только к техписам относится :)
Да, естественно. Но при этом
Да, естественно.
Но при этом программистов можно как-то организовать "сверху вниз", в мелкие рабочие группы с четко определенной задачей.
А тестеры и писатели
а) имеют дело с самым верхним уровнем (целым продуктом)
б) оба способа организации связи с девелоперами - и через верх и прямые (не вверх-вниз по иерархии) - имеют крупные недостатки.
Для себя я вроде бы понял, что я просто в больших структурах не хочу работать. В середине не хочу, близко к самому верху - тоже не хочу, а в самый низ меня не возьмут.
Ну представим, что у нас есть
Ну представим, что у нас есть менеджер продукта ( как роль) который заинтересованно контролирует горизонтальные коммуникации. И в чём будут недостатки?
Чётко организовать можно все роли, если понятно зачем, сложнио принять, что девелоперы не главнее писателей или тестеров. Но привыкнуть можно.
Про целый продукт -- когда-то да, бывает, не от хорошей жизни. Но работа писателя вообще может начаться раньше работы кодеров, а тестеры работают и с модулями и с прототипами. Btw тут писательство вообще инженерная работа, а не беллетристическая. Ну в том смысле, что слово -- топор инженера. :)
Ну тут же вопрос выданных
Ну тут же вопрос выданных привилегий и подходов. У нас, например, где не было юзабилиста - отчасти тот же техпис выступал в этой роли, общался со внутренними пользователями, например, и выдавал вопросы, и мы их фиксили ...
где-то вообще есть юзабилист, и что он не заметил, и программист пропустил, вполне ему может показать/спросить и техпис ...
ну а в случае "одиночки с мотором", как я вижу, народ чаще всего просто использует бета-тестеров, которые за халявный ключик пишут репорты и чего не понравилось ... там, правда, появляется вопрос как правильную группу тестеров, соответствующую юзерам, набрать ...
Ну разделение труда не отменяет обратных связей. Есть, опять
Ну разделение труда не отменяет обратных связей. Есть, опять же, и аудит и проверка юзабилити, да и комментарии писателя не обязательно сразу в шредер. Скорее не противоречие, а вопрос правильной организации труда.
Если архитектор как глухарь на току -- то это, конечно, проблема, но тоже не вполне логическая.
Как я уже <a href=http://blog.lexa.ru/2012/01/30/o_tekhniche
Как я уже написал в первоисточнике, проблема не только в организации труда, но и в постоянной времени этой обратной связи.
Когда мы продавали один наш продукт (с потрохами) в одну большую софтверную компанию, тамошние тестеры сказали нам, что цикл тестирования займет месяца четыре. Так примерно и получилось.
Связи и организация труда --
Связи и организация труда -- это в том смысле что любая деятельность, а не только кодирование требует верификации. Для кодирования грабли просто в шаговой доступности.
По времени -- так тоже есть особенности, асинхронный ACK придумали довольно давно. Ну то есть не всегда работы должны быть строго и целиком последовательны.
А ещё могут тестеры писать.
А ещё могут тестеры писать. Всё логично.
а где в конце сокраментальное "Что делат? Кто виноват?? Где
а где в конце сокраментальное "Что делат? Кто виноват?? Где водка??? (с)" ;)
А нет ответа. Чем меньше команда, тем меньше оверхед и тем
А нет ответа.
Чем меньше команда, тем меньше оверхед и тем больше шансов, что мануал будет писать генеральный директор лично.
Чем больше команда, тем больше (теоретически) можно сделать за фиксированное время.
А вопрос с количественной оценкой оверхеда от увеличения команды - интересный, но бессмысленный.
и в сутках всего 24 часа всю работу не переделаешь - на част
и в сутках всего 24 часа
всю работу не переделаешь - на часть придётся забить! (с)
в общем всё сильно от людей(команды) и руководства этими людьми зависит
прогнозировать тут сложно
слишком глубокое разделение труда привело современную цивили
слишком глубокое разделение труда привело современную цивилизацию к экономическому кризису.
ну и райкин не зря упомянут.
По моему опыту техписатель может повышать качество продукта,
По моему опыту техписатель может повышать качество продукта, если он:
а) четко понимает что может и должен говорить о косяках в продукте
б) транзакции с разработчиками дешёвые по логистике, например он сидит в одной комнате с разработчиками и всегда может спросить что и почему так сделано.
хотя тут, конечо, сложно соблюсти баланс излишне въедливый чувак может довести разработчиков до белого каления, например.
Практико
В моем небедном жизненном опыте рабочей себя зарекомендовала такая схема:
1. Техписа надо брать обязательно энтузиаста продукта. Т.е. он лично должен быть продвинутым юзером продукта (для себя), а не простым акыном.
2. Если получится на него же навесить саппорт ендюзеров - вообще отлично. FAQ составлять, переписку с ендюзерами вести...
3. "Самому главному" в проекте надо обязательно вычитывать креатиффы техписа. Для отлова нездоровых сенсаций. А вот писать при этом самому главному - нет необходимости.
Пользователь-энтузиаст зачастую лучше девелоперов ориетнируется в функциональности продукта, особенно, если эта функциональность - сложная.
Вербовать таких техписов можно тоже из переписки техсаппорта - кто больше замучит вопросами техсаппорт, того и звать на интервью на предмет занятия должности техписа.
Даже в случае скучных бухгалтерско-корпоративных продуктов - можно найти энтузиаста среди юзеров. Ну а если ты сделал продукт, который никому не нужен - то техпись-не-техпись его - хорошо не будет.
Это я все к тому, что:
> найм техписателя для написания доки автоматически означает ухудшение качества
> продукта (в хорошем случае - с одновременным улучшением качества документации).
- возможно избежать. Т.е. хороший техпис - таки да, улучшает продукт. И весьма заметно.
Есть в этом определённая
Есть в этом определённая самодеятельность, то есть как сделать софтверную команду с помощю палки и верёвки. Нет, не подумайте, что я тут выпендриваюсь, просто прежде чем упрощать и допускать исходя из возможностей, надо представлять что бы было в идеале.
А в идеале технический писатель не должен быть литератором и уж точно графоманом. Технический писатель должен быть инженером, а прибаутки стоит оставить для книжек сторонних авторов.
У меня тоже был опыт работы с документацией ( я занимался локализацией и редактурой), так вот литературных изысков в хорошей документации до смешного мало, довольно однообразный текст, часто на умышленно бедном словаре. Основная задача -- помочь пользователю узнать продукт и стать в нём специалистом. Писатель должен уметь связно, компактно и понятно объяснить как работает продукт, от общей схемы и концепции, до функциональности, спецификаций и т.д.
Из этого следует, что такой инженер должен понимать всю схему продукта, взаимосвязи между частями, причины и следствия технических решений. И, конечно, реализацию. То есть это высокоуровневый инженер, с дополнительными навыками в области создания документов. Профессор! :)