Хочется помочь вам не опускать руки поэтому я попинаю вашу статью еще немного :) Тем более что для Хабра она по тематике подходит и не думаю что кто-то знает вас лично, чтобы минусить из личной неприязни.
Первая ваша ошибка была в том, что вы написали статью в предположении что ее никто не будет читать. Хабр весьма посещаемый сайт и статьи, тем более с таким интересным заголовком как у вас, неизбежно привлекут внимание аудитории. Вторая ошибка в том, что содержание статьи не оправдывает интригующего названия. Люди зашли, прочитали, не увидели ничего нового и интересного для себя, поставили минус. Если бы статья называлась "8 банальных тезисов о том что нужно сделать, чтобы продвинуть канал", то может быть минусов было бы меньше. А если серьезно, там по каждому тезису можно было бы по странице текста развернуть, с примерами и подводными камнями, это был бы крутой материал.
Если пишете статью для людей, постарайтесь что-то рассказать им и как-то развлечь. Опишите проблематику и детали решений. А если пишете свои заметки в черновик, оставьте его в гуглодоке, на него тоже можно дать ссылку работодателю, но его не заминусят публично.
Да, я тоже думал о том, что кофемолка может быть не самый удачный пример. Нужно было вспомнить о чем-то, чем только мужики пользуются. Типа какой-нибудь штуки для рыбалки. Мы точно эти инструкции не читаем :)
"Производство IT-продуктов" это не "manufacturing". Да и не "производство", а "разработка", если на то пошло. Я думаю, что речь про физическое производство.
На сайте Divio изложены эти же идеи, этим же словами и этим же автором, он в то время работал на Divio. Но Diataxis это официальное название этого подхода, чтобы вам не приходилось выдумывать свое, типа "Великой, единой...". На теорию всего он, кстати, не претендует. Это вообще не теория. Это практический подход к созданию пользовательской (!) документации. И то, в какой мере вам удобно этот подход применять, решать только вам. Это зависит и от системы и от ЦА и других факторов. И автор об этом честно пишет.
Как минимум, запятая перед that ошибочна во втором примере.
Допустим запятой там нет. Тогда второй пример означает, что определением SSL-протокола является то, что он широко распространен. Это несколько лишено смысла :)
Суть проста — which вводит дополнительную информацию, а that — определяющую. Собственно, об этом в статье и написано.
Я имел ввиду, что зарплата техписа в среднем по рынку ниже, чем зарплата аналитика. Значит если техпис делает работу аналитика за зарплату техписа, значит это аналитик, которому не доплачивают. За зарплату разработчика поработать аналитиком наверное не так уж плохо.
На концепции и справочники лучше всего ссылаться в тексте при первом упоминании термина. Например, в гайде "Как настроить VPN" в первой строчке у вас будет "Чтобы настроить [VPN](ссылка на концепцию, где описано что такое VPN) : ...".
А на гайды и туториалы можно ссылаться в конце раздела или параграфа. То есть в конце концепции "Что такое VPN?" у вас будет параграф типа "См. также: Как настроить VPN, Настраиваем VPN на iOS (ссылки на гайды и туториалы, соотвтетственно)".
Но это всё не правила, просто рекомендации из моего опыта. Нужно смотреть по возможности и здравому смыслу где ссылки на другие разделы будут уместны.
Спасибо за развернутый ответ. Я с геймдев-документацией не сталкивался еще, поэтому может быть какой-то специфики не понимаю. Хотя это очень интересно должно быть.
Ваша статья могла бы быть более увлекательной, если бы вы о таких неочевидных и специфичных вещах в ней последовательно написали. Без связующих пояснений цели, задач и процесса разработки документации, статья выглядит как набор случайно взятых фактов и советов. Отсюда впечатление, что статью писал ИИ.
Как-то сумбурно получилось, вы точно не ChatGPT? :)
О какого рода документации вообще речь? В начале вы говорите о требованиях, то есть о проектной документации. Затем вы упоминаете актуальность и доступность документации для пользователей, то есть теперь говорите о пользовательской документации. Затем речь опять заходит про требования, то есть опять про проектную.
У этих видов документации разные цели и задачи, разная аудитория, по идее ее пишут разные люди и на разных этапах жизненного цикла продукта. Наверное и подходы к тестированию совершенно разные должны быть.
Каким образом читы относятся к разработке доки тоже тема не раскрыта.
Перевод художки это вообще только по призванию и только если у вас есть кто-то, кто готов вас содержать, так как есть будет нечего. За это платят часто даже меньше, чем техническим переводчикам низшего звена, а труд титанический. Нужно самому быть художественным писателем по сути. А автопереводу нормальная художка не поддается, смысла в нем нет.
Отвечу на правах бывшего технического переводчика.
Вынужден не согласится с самым первым вашим утверждением. Переводы дело нудное только если вы не любите переводить. Для того, кто любит, это увлекательный процесс. А вот про неблагодарное и малооплачиваемое полностью согласен с вами.
Далее. Не обязательно досконально и глубоко понимать написанное, а тем более применять на практике в программировании, чтобы нормально перевести. Перевод несомненно требует погружения в предметную область, но на существенно меньшую глубину, чем та, которая нужна программисту для практики. Но просто хороший переводчик, как минимум, разберется в принятой терминологии и таких ляпов как тут не допустит. Какие-то тонкие моменты от переводчика, конечно, могут ускользнуть. В нормальном мире мире розовых поней и эльфов в этот момент в игру вступает технический редактор, который как раз проверяет текст на технические неточности.
Проблема в том, что как хорошего переводчика, так и ответственного технического редактора нужно сперва найти, что непросто, когда каждый первый считает, что способен быть переводчиком (это не так, ребята). Потом им нужно заплатить столько денег, чтобы они не только покушать, но и за коммуналку заплатить смогли. В целом этого достаточно, чтобы книжка получилась норм. Но, видимо, ответственный за издательство этой книжки решил сэкономить и нанял первого попавшегося первокурсника за 150р./стр., а с поиском технического редактора вообще не парился.
Еще могу почти наверняка сказать, что это не машина переводила. Машины не ошибаются так тупо при переводе групп существительных с артиклем типа "a classification algorithm".
Хочется помочь вам не опускать руки поэтому я попинаю вашу статью еще немного :) Тем более что для Хабра она по тематике подходит и не думаю что кто-то знает вас лично, чтобы минусить из личной неприязни.
Первая ваша ошибка была в том, что вы написали статью в предположении что ее никто не будет читать. Хабр весьма посещаемый сайт и статьи, тем более с таким интересным заголовком как у вас, неизбежно привлекут внимание аудитории. Вторая ошибка в том, что содержание статьи не оправдывает интригующего названия. Люди зашли, прочитали, не увидели ничего нового и интересного для себя, поставили минус. Если бы статья называлась "8 банальных тезисов о том что нужно сделать, чтобы продвинуть канал", то может быть минусов было бы меньше. А если серьезно, там по каждому тезису можно было бы по странице текста развернуть, с примерами и подводными камнями, это был бы крутой материал.
Если пишете статью для людей, постарайтесь что-то рассказать им и как-то развлечь. Опишите проблематику и детали решений. А если пишете свои заметки в черновик, оставьте его в гуглодоке, на него тоже можно дать ссылку работодателю, но его не заминусят публично.
Я думаю hashishka имел ввиду статьи в целом и причины по которым статью могут заминусить. Это не относится к данной статье.
Да, я тоже думал о том, что кофемолка может быть не самый удачный пример. Нужно было вспомнить о чем-то, чем только мужики пользуются. Типа какой-нибудь штуки для рыбалки. Мы точно эти инструкции не читаем :)
Классная статья, спасибо
"Производство 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".