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