О техническом писательстве

Пишу доку к варезу, первый раз за много лет - для обычного пользователя, сферического в вакууме (все что писал в последние годы - было доками по библиотекам т.е. для программистов).

Нашел в самой задаче крупное логическое противоречие:

  1. С одной стороны: загружать разработчика такой работой - противоречит самой идее разделения труда. Архитекторы должны архитектить, кодеры - кодить, тестеры - тестить, технические писатели - писать мануалы, а специалисты по пуговицам - пришивать пуговицы.
  2. С другой стороны: технический писатель имеет дело с черным ящиком. Он не знает что там внутри, если в программе вдруг что-то нелогично, то не его (писательское) дело против этого протестовать. Ему что дали - про то он и споет.

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

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

У меня нет никакого конструктива, понятно что варез большого размера в одно рыло не разработать, а значит разделение труда - необходимо(е зло). Но все вместе наводит на меня тоску: найм техписателя для написания доки автоматически означает ухудшение качества продукта (в хорошем случае - с одновременным улучшением качества документации).

Comments

IMHO: доку надо писать в два этапа. На первом этапе разраб документирует и сам все нелогичности вылавливает, на втором этапе тех. писатель переводит документацию на человеческий язык.

Не вполне про юзерский софт, а про библиотеки. В библиотеках это кончается тем что
- документация генерируется автоматом, через Doxygen
- никто ее не правит, ибо править результаты работы автомата бессмысленно, править надо исходник, а кто туда пустит техписателя.
- полезность документации в единицах полезности на килобайт уверенно стремится к нулю.

ну тут вопрос кто чего хочет опять-таки ...

у нас вот техписы регулярно делают ревью тех же строк локали, и вообще сообщений и т.д., и есть процесс их правки ...

Локаль-сообщения - это понятно, но мелко.

У меня вот, например, "нарушилась связь времен" - т.е. утерялось обновление данных в одной дырочке при изменении параметров в другой.

Внешний писатель не имеет шансов это заметить, не то что внятно рассказать.

ну ты ж сам пишешь про автодокументацию - такое техпис может найти вполне и баг забить :)

про нарушения самого апи - ну тут оппаньки, только юнит тестами и прочими тестами ...

- документация генерируется автоматом, через Doxygen

Это должна быть тока для техписа, а не конечная. Ессна, надо смотреть дифы для синхронизации.

Править руками результаты компиляции (Doxygen) - это как править руками (со всеми диффами и т.п.) ассемблер после компилятора.

Можно, но по сути - издевательство.

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

Ну, и да, не забываем про модное нынче слово юзабилити-тестирование.

У тестеров это обратная связь подразумевается изначально, иначе зачем все это.
У писателей - подразумевается не всегда. Но так - я согласен, конечно нужна обратная связь.

Но при этом надо отдавать себе отчет, что время реакции в сколько-нибудь большом коллективе будет не две минуты, а скорее две недели. Отчего процесс сходиться будет медленно, а оверхеду будет вагон.

время реакции в сколько-нибудь большом коллективе будет не две минуты, а скорее две недели. Отчего процесс сходиться будет медленно, а оверхеду будет вагон.

Мне кажется, это не только к техписам относится :)

Да, естественно.

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

Для себя я вроде бы понял, что я просто в больших структурах не хочу работать. В середине не хочу, близко к самому верху - тоже не хочу, а в самый низ меня не возьмут.

Ну представим, что у нас есть менеджер продукта ( как роль) который заинтересованно контролирует горизонтальные коммуникации. И в чём будут недостатки?

Чётко организовать можно все роли, если понятно зачем, сложнио принять, что девелоперы не главнее писателей или тестеров. Но привыкнуть можно.

Про целый продукт -- когда-то да, бывает, не от хорошей жизни. Но работа писателя вообще может начаться раньше работы кодеров, а тестеры работают и с модулями и с прототипами. Btw тут писательство вообще инженерная работа, а не беллетристическая. Ну в том смысле, что слово -- топор инженера. :)

Ну тут же вопрос выданных привилегий и подходов. У нас, например, где не было юзабилиста - отчасти тот же техпис выступал в этой роли, общался со внутренними пользователями, например, и выдавал вопросы, и мы их фиксили ...

где-то вообще есть юзабилист, и что он не заметил, и программист пропустил, вполне ему может показать/спросить и техпис ...

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

Ну разделение труда не отменяет обратных связей. Есть, опять же, и аудит и проверка юзабилити, да и комментарии писателя не обязательно сразу в шредер. Скорее не противоречие, а вопрос правильной организации труда.

Если архитектор как глухарь на току -- то это, конечно, проблема, но тоже не вполне логическая.

Как я уже написал в первоисточнике, проблема не только в организации труда, но и в постоянной времени этой обратной связи.

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

Связи и организация труда -- это в том смысле что любая деятельность, а не только кодирование требует верификации. Для кодирования грабли просто в шаговой доступности.

По времени -- так тоже есть особенности, асинхронный ACK придумали довольно давно. Ну то есть не всегда работы должны быть строго и целиком последовательны.

А ещё могут тестеры писать. Всё логично.

а где в конце сокраментальное "Что делат? Кто виноват?? Где водка??? (с)" ;)

А нет ответа.

Чем меньше команда, тем меньше оверхед и тем больше шансов, что мануал будет писать генеральный директор лично.

Чем больше команда, тем больше (теоретически) можно сделать за фиксированное время.

А вопрос с количественной оценкой оверхеда от увеличения команды - интересный, но бессмысленный.

и в сутках всего 24 часа
всю работу не переделаешь - на часть придётся забить! (с)

в общем всё сильно от людей(команды) и руководства этими людьми зависит
прогнозировать тут сложно

слишком глубокое разделение труда привело современную цивилизацию к экономическому кризису.
ну и райкин не зря упомянут.

По моему опыту техписатель может повышать качество продукта, если он:

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

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

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

1. Техписа надо брать обязательно энтузиаста продукта. Т.е. он лично должен быть продвинутым юзером продукта (для себя), а не простым акыном.

2. Если получится на него же навесить саппорт ендюзеров - вообще отлично. FAQ составлять, переписку с ендюзерами вести...

3. "Самому главному" в проекте надо обязательно вычитывать креатиффы техписа. Для отлова нездоровых сенсаций. А вот писать при этом самому главному - нет необходимости.

Пользователь-энтузиаст зачастую лучше девелоперов ориетнируется в функциональности продукта, особенно, если эта функциональность - сложная.

Вербовать таких техписов можно тоже из переписки техсаппорта - кто больше замучит вопросами техсаппорт, того и звать на интервью на предмет занятия должности техписа.

Даже в случае скучных бухгалтерско-корпоративных продуктов - можно найти энтузиаста среди юзеров. Ну а если ты сделал продукт, который никому не нужен - то техпись-не-техпись его - хорошо не будет.

Это я все к тому, что:
> найм техписателя для написания доки автоматически означает ухудшение качества
> продукта (в хорошем случае - с одновременным улучшением качества документации).
- возможно избежать. Т.е. хороший техпис - таки да, улучшает продукт. И весьма заметно.

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

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

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

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

Add new comment