Comments 12
из реальной жизни - бываеи, что нет никакой документации по коду, который надо существенно изменить. Программист был в коме когда писал его или уже ушел, или он записал ролик, один, и считает свой долг по документированию исполненным чуть больше. чем полностью. Начинается reverse engineering - тоже своего рода прокрастенация и это затягивает не хуже чем "это надо проверить", тем более, что, как правило, такой подход подразумевает, что надо проверить всё. И надо бы уже что-то начать делать по изменениям, но еще есть столько всего попроверять. Вдохновение, наверное, не приходит.
По поводу "это так не работает", "это не так" и пункта 6 - а что, техписатель пишет документацию по программе, не запуская её сам и не проверяя, как она работает? Или ему присылают скриншоты, и он по ним сам догадывается, как программа работает, и что делают все кнопки в ней?
Про пункт 5 - есть какие-то критерии оценки, имеет ли кто-то право писателю делать рекомендации по поводу стиля? Может, надо сначала предъявить кучу сертификатов с регалиями, по которым техписатель сразу поймёт, следовать рекомендациям проверяющего или нет?
Документ пишет писатель, он и будет отвечать.
Разве это не так?
"Так не работает" - обычно логику поменяют, техписов не уведомят, а ревьюер или представления не имеет, какая версия/итерация описана, или и есть тот, кто не уведомил.
Есть. Если ревьюер не в теккоммс и нет профильного (филологического) образования и/или нет аргументации по предлагаемой стилистической правке - идет лесом, включая ПМов.
обычно логику поменяют, техписов не уведомят
В смысле, им не дают актуальную версию программы, они работают в старой и ее описывают в документации?
Если ревьюер не в теккоммс и нет профильного (филологического) образования
Не смешите мои тапочки. У меня нет филологического образования, но я встречал достаточно филологов, за которыми приходилось исправлять ошибки как грамматические, так и стилистические. Образование вообще не является гарантией того, что человек умеет связно излагать свои мысли, не то что обращать их в письменный вид.
В смысле, им не дают актуальную версию программы, они работают в старой и ее описывают в документации?
Не всегда версионность есть. А так, да, поменяли логику в фиче, UI, дизайн - а техписа не уведомили. Техпис описал предыдущую итерацию и работает над другим разделом. Сплошь и рядом, к сожалению, и на условном Востоке, и на условном Западе.
Не смешите мои тапочки. У меня нет филологического образования, но я встречал достаточно филологов, за которыми приходилось исправлять ошибки как грамматические, так и стилистические.
Ну, с таким подходом вы, наверное, и стоматологам советуете, как зубы лечить. Наличие некомпетентных специалистов до какой-то степени оправдывает подход "да кто ты такой, вот так надо", но это не должно быть нормой. Опять же, зависит от применяемых стандартов. При документировании по ГОСТам и ЕСКД не требуются какие-то специфичные языковые навыки, грамотности и аккуратности достаточно, насколько помню по давней работе.
По большому счету, претензии техписов всегда сводятся к двум моментам:
Давайте полную и актуальную информацию, не за день до дедлайна.
В случае критики, обозначьте конкретные недостатки критикуемого материала - чего не хватает, что неверно. А уж если есть дополнительные (внутренние) источники информации - отлично, поделитесь, техпис будет признателен вам за это.
Стоматологам я, конечно, ничего не советую. Но бывают грубые стилистические ошибки, грамматические и прочие, которые очевидны грамотному человеку. Так получилось, что я определенное количество лет вычитывал документацию за техписателями, хоть я и программист. Когда пропущена запятая, тут всё понятно, а если ошибка фактическая или стилистическая, я всегда писал рекомендации, как написать лучше.
В прошлом занимался написанием отчетов. При прочтении собрал 13 из 17 пунктов, которые встречал:)
У меня встречался еще комментарий - "Переформулировать". Обычно выделялось 10-15 строк и помечалось данным комментарием, без дополнительных разъяснений.
Да, пункт 4 самый цимес, с единственным знаком вопроса в качестве комментария.
17 вредных советов для тех, кто проверяет документацию и технические тексты