Как стать автором
Обновить
43
0
Константин Макушев @makushevkm

Технический писатель

Отправить сообщение

Классная статья, спасибо

"Производство IT-продуктов" это не "manufacturing". Да и не "производство", а "разработка", если на то пошло. Я думаю, что речь про физическое производство.

Полезная статья. Многие советы отсюда полезны не только для улучшения машинного перевода, но и в целом справедливы для хорошего текста.

Правильнее ссылаться на https://diataxis.fr/

На сайте Divio изложены эти же идеи, этим же словами и этим же автором, он в то время работал на Divio. Но Diataxis это официальное название этого подхода, чтобы вам не приходилось выдумывать свое, типа "Великой, единой...". На теорию всего он, кстати, не претендует. Это вообще не теория. Это практический подход к созданию пользовательской (!) документации. И то, в какой мере вам удобно этот подход применять, решать только вам. Это зависит и от системы и от ЦА и других факторов. И автор об этом честно пишет.

На Хабре, кстати, есть другая статья про этот же подход: https://habr.com/ru/companies/documentat/articles/766926/

Впрочем, как сторонник подхода, я рад, что про него появляются еще статьи и больше людей про него узнает :)

Спасибо за отзыв!
Про пусек бятых я, кстати, не знал. Думал про другой хрестоматийный пример — Глокая куздра :)

Товарищи синьор-разрабы, проходите мимо, не задерживайте очередь, это не для вас написано :)

Как минимум, запятая перед that ошибочна во втором примере.

Допустим запятой там нет. Тогда второй пример означает, что определением SSL-протокола является то, что он широко распространен. Это несколько лишено смысла :)

Суть проста — which вводит дополнительную информацию, а that — определяющую. Собственно, об этом в статье и написано.

С этого ошибочного варианта мы и начали блок :)

Я имел ввиду, что зарплата техписа в среднем по рынку ниже, чем зарплата аналитика. Значит если техпис делает работу аналитика за зарплату техписа, значит это аналитик, которому не доплачивают.
За зарплату разработчика поработать аналитиком наверное не так уж плохо.

Зависит от команды, но вообще по-хорошему любое ТЗ пишет аналитик. Если ТЗ пишет техпис, то он и есть аналитик, просто ему недоплачивают.

Хороший вопрос, спасибо.

На концепции и справочники лучше всего ссылаться в тексте при первом упоминании термина. Например, в гайде "Как настроить VPN" в первой строчке у вас будет "Чтобы настроить [VPN](ссылка на концепцию, где описано что такое VPN) : ...".

А на гайды и туториалы можно ссылаться в конце раздела или параграфа. То есть в конце концепции "Что такое VPN?" у вас будет параграф типа "См. также: Как настроить VPN, Настраиваем VPN на iOS (ссылки на гайды и туториалы, соотвтетственно)".

Но это всё не правила, просто рекомендации из моего опыта. Нужно смотреть по возможности и здравому смыслу где ссылки на другие разделы будут уместны.

Для примера можете посмотреть как на пошаговые инструкции ссылаются из концепций, и наоборот, на Яндекс Облаке: https://cloud.yandex.ru/docs/managed-postgresql/concepts/backup

Союз айтишников России не за горами. Будут решать кто программист, а кто нежелательный элемент.

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

Ваша статья могла бы быть более увлекательной, если бы вы о таких неочевидных и специфичных вещах в ней последовательно написали. Без связующих пояснений цели, задач и процесса разработки документации, статья выглядит как набор случайно взятых фактов и советов. Отсюда впечатление, что статью писал ИИ.

Как-то сумбурно получилось, вы точно не ChatGPT? :)

О какого рода документации вообще речь? В начале вы говорите о требованиях, то есть о проектной документации. Затем вы упоминаете актуальность и доступность документации для пользователей, то есть теперь говорите о пользовательской документации. Затем речь опять заходит про требования, то есть опять про проектную.

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

Каким образом читы относятся к разработке доки тоже тема не раскрыта.

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

Почему бы издательствам не завязать издавать то, что не могут себе позволить качественно перевести?

Отвечу на правах бывшего технического переводчика.

Вынужден не согласится с самым первым вашим утверждением. Переводы дело нудное только если вы не любите переводить. Для того, кто любит, это увлекательный процесс. А вот про неблагодарное и малооплачиваемое полностью согласен с вами.

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

Проблема в том, что как хорошего переводчика, так и ответственного технического редактора нужно сперва найти, что непросто, когда каждый первый считает, что способен быть переводчиком (это не так, ребята). Потом им нужно заплатить столько денег, чтобы они не только покушать, но и за коммуналку заплатить смогли. В целом этого достаточно, чтобы книжка получилась норм. Но, видимо, ответственный за издательство этой книжки решил сэкономить и нанял первого попавшегося первокурсника за 150р./стр., а с поиском технического редактора вообще не парился.

Еще могу почти наверняка сказать, что это не машина переводила. Машины не ошибаются так тупо при переводе групп существительных с артиклем типа "a classification algorithm".

Помилосердствуйте! "Чистой" энергии не существует. Или во всяком случае не открыто и даже в теории не предсказано. Наверное вы хотели сказать "энергия бозонов"?

Читайте классику.

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

Оставьте пустые "философские" спекуляции на эту тему, к науке они точно не имеют отношения.

Объясните как работает "Секретная номинация"? Туда попадут статьи, которые жюри сочтут не вполне подходящими по тематике под другие номинации? Или по-другому?

1

Информация

В рейтинге
Не участвует
Откуда
Алматы (Алма-Ата), Алма-Атинская обл., Казахстан
Дата рождения
Зарегистрирован
Активность

Специализация

Technical Writer
Markdown
Writing instructions
Technical translation
Russian language
English
Git
Linux
Cloud computing
Database
Swagger