инструкции к бытовым приборам, написанные по логике 50-летней давности, часто приводят в качестве очень плохих примеров на курсах и воркшопах техписов. не стоит их равнять с нормальной документацией для IT-продуктов.
очень толково. такие когнитивные искажения вижу и у себя, и у новичков. мне кажется очень правильным спокойное отношение к незнанию, к ошибкам, к тому, что нужно задавать вопросы и говорить. я вижу, что это действительно помогает справиться с огромной нагрузкой, падающей на новеньких.
ох, я тоже техпис, и знакома с этой проблемой. мне помогает такое отношение: я понимаю, что это разработчик, который сделал фичу, и только он знает, как именно она здесь работает. только ПМ знает, что именно об этой фиче должен знать юзер. моя здесь обязанность - выяснить, что у них в голове, и с учетом этого сделать мою работу - описать. я сначала, конечно, делаю рисерч, но этого никогда не хватает - все равно надо спрашивать про специфику. а мысли читать я все еще не умею, поэтому спокойно спрашиваю и игнорирую закатывание глаз. я, кстати, редко с такой реакцией встречаюсь, но все равно бывает, и к этому надо быть готовым.
да, поэтому нужно хорошо себе представлять целевую аудиторию. как раз такие сложности и снимаются, что одному понятно, другому нет. особенно хорошо, когда есть возможность на ЦА потестировать доки. да и продукт, чего уж там.
очень ценный комментарий, спасибо. и добавим к этому еще русское словообразование, когда суффиксы и окончания создают столько новых длинных форм от одного корня, а в английском слово часто меняет часть речи, оставаясь простым и коротким. в итоге объем текста вырастает значительно.
А как вы себе представляете "2-й способ, когда позиция имеет фиксированное место с дискретным углом 45º и фиксированным удалением от точки пересечения графика с визиром"? Это не совсем то же самое, что в определённых местах, как на кроватях и диванах.
Проблема не в том, что этот текст недостаточно понятен лично мне, он будет недостаточно понятен пользователю. И это мы проверяли на ЦА. Это значит, что, прочитав текст один раз, пользователь не поймёт сразу, о чем речь. И он будет читать второй раз, стараться, а это те усилия, которых не должно быть. Или он не поймёт и пропустит, а это тоже несостоявшаяся коммуникация, цель не достигнута. Этот конкретный текст нужно упростить и сделать понятнее.
А поводу терминологии, в таком документе, конечно, вариант каждого термина будет везде один. Но какой, нужно решать с конкрентным документом. Вообще придётся как-то так балансировать, чтобы читатель просто не ушел: новичок уйдёт от слишком сложного текста, а продвинутый от слишком простого. Если никак нельзя разделить аудиторию, нужно хотя бы представлять себе количественное соотношение разных персон в ней, а также их цели.
Понятно, спасибо. Да, есть документы, для которых аудитория не определена или слишком широкая. Писать такие документы сложно, потому что текст должен быть понятен начинающим и не слишком замусорен для продвинутых. Есть несколько лайфхаков: убирать объяснения и определения из основного массива, например, во всплывающие подсказки. Так их можно увидеть, если нужно, а можно не наводить мышку, и не увидишь. А ещё убирать информацию, не нужную всем в отдельные секции, и на них ссылаться. Кто захочет — прочитает, кто и так знает — перескочит. Подробнее я хочу описать это в статье про навигацию и linking.
О, навигация — это тема следующей статьи. Как сделать так, чтобы читатель знал, какой шаг (раздел) следующий, и есть ли предыдущий, который ему тоже нужно прочитать. Как эту информацию преподнести так, чтобы она не мешала по тексту, но чтобы её можно было найти. Тема очень сложная и очень специфичная: в разных документах по-разному.
Вот одну из причин вы назвали, я согласна. Когда мы описываем софт, лексика для него в основном идёт из английского. И в английском это естественно звучит, а в русском не очень, приходится дополнять и объяснять.
я знаю о разделении аудитории и создании разных гайдов для админов и для конечных пользователей. а вот об объединении, что было два, а стал один гайд, я не слышала. расскажите поподробнее, что вы имеете в виду под «объединением аудитории»?
согласна. а еще, иногда выражения на разных языках у меня вызывают разный отклик в душе, и они отражают разные эмоции. поэтому вроде говоришь по-русски, но как-то не находишь аналога в своем языке, и говоришь какие-то междометия, или короткие ситуативные фразы на английском. потому что они вот в этой ситауции лучше отражают. например: Oh my Gosh! Oh no. Yay! а я еще в свое время изучала (и даже преподавала) фонетику английского, поэтому еще и интонация другая, нерусская, и звучит забавно) а когда по-английски говорю, часто не могу найти аналога русского мата, и тоже его вставляю прямо в английскую речь)
Спасибо. Статья получилась такая настоящая, как будто с другом поговорила.
инструкции к бытовым приборам, написанные по логике 50-летней давности, часто приводят в качестве очень плохих примеров на курсах и воркшопах техписов.
не стоит их равнять с нормальной документацией для IT-продуктов.
нам весело писать нескучные тексты.
очень толково. такие когнитивные искажения вижу и у себя, и у новичков. мне кажется очень правильным спокойное отношение к незнанию, к ошибкам, к тому, что нужно задавать вопросы и говорить. я вижу, что это действительно помогает справиться с огромной нагрузкой, падающей на новеньких.
ох, я тоже техпис, и знакома с этой проблемой. мне помогает такое отношение: я понимаю, что это разработчик, который сделал фичу, и только он знает, как именно она здесь работает. только ПМ знает, что именно об этой фиче должен знать юзер. моя здесь обязанность - выяснить, что у них в голове, и с учетом этого сделать мою работу - описать. я сначала, конечно, делаю рисерч, но этого никогда не хватает - все равно надо спрашивать про специфику. а мысли читать я все еще не умею, поэтому спокойно спрашиваю и игнорирую закатывание глаз. я, кстати, редко с такой реакцией встречаюсь, но все равно бывает, и к этому надо быть готовым.
Девчонка просто молодец, удачи и так держать!
Текст огонь! И тэг тоже зачётный
Очень полезно и интересно, спасибо! Можно положить в хаб "Подготовка технической документации", очень в тему.
А как вы себе представляете "2-й способ, когда позиция имеет фиксированное место с дискретным углом 45º и фиксированным удалением от точки пересечения графика с визиром"? Это не совсем то же самое, что в определённых местах, как на кроватях и диванах.
Проблема не в том, что этот текст недостаточно понятен лично мне, он будет недостаточно понятен пользователю. И это мы проверяли на ЦА. Это значит, что, прочитав текст один раз, пользователь не поймёт сразу, о чем речь. И он будет читать второй раз, стараться, а это те усилия, которых не должно быть. Или он не поймёт и пропустит, а это тоже несостоявшаяся коммуникация, цель не достигнута. Этот конкретный текст нужно упростить и сделать понятнее.
А поводу терминологии, в таком документе, конечно, вариант каждого термина будет везде один. Но какой, нужно решать с конкрентным документом. Вообще придётся как-то так балансировать, чтобы читатель просто не ушел: новичок уйдёт от слишком сложного текста, а продвинутый от слишком простого. Если никак нельзя разделить аудиторию, нужно хотя бы представлять себе количественное соотношение разных персон в ней, а также их цели.
Понятно, спасибо. Да, есть документы, для которых аудитория не определена или слишком широкая. Писать такие документы сложно, потому что текст должен быть понятен начинающим и не слишком замусорен для продвинутых. Есть несколько лайфхаков: убирать объяснения и определения из основного массива, например, во всплывающие подсказки. Так их можно увидеть, если нужно, а можно не наводить мышку, и не увидишь. А ещё убирать информацию, не нужную всем в отдельные секции, и на них ссылаться. Кто захочет — прочитает, кто и так знает — перескочит. Подробнее я хочу описать это в статье про навигацию и linking.
О, навигация — это тема следующей статьи. Как сделать так, чтобы читатель знал, какой шаг (раздел) следующий, и есть ли предыдущий, который ему тоже нужно прочитать. Как эту информацию преподнести так, чтобы она не мешала по тексту, но чтобы её можно было найти. Тема очень сложная и очень специфичная: в разных документах по-разному.
Вот одну из причин вы назвали, я согласна. Когда мы описываем софт, лексика для него в основном идёт из английского. И в английском это естественно звучит, а в русском не очень, приходится дополнять и объяснять.