Комментарии 18
А конвеншнс для юзера сделали? Откуда он знает, что плашкой, а что курсивом? И как с длинными тире и проч спецсимволамм в UI коде? Удивительно, что есть время на рефакторинг стайлгайда. Кого-то из молодых да новых сотрудников на это бросили?
Привет, спасибо за комментарий! Мы как раз в стайлгайде описали, в каких кейсах какой инструмент используется, например где использовать разноцветные плашки, табы или болд) И это в первую очередь внутренний инструмент и набор правил от техписов Ozon для техписов Ozon (и техписов других компаний, которые могут им вдохновиться, конечно!)
Про UI-код не очень поняла вопрос, получится ли перефразировать?
И да, стайлгайд мы действительно готовили довольно долго, больше полугода, и выкраивали для него время среди большого потока задач. Но для этого достаточно было пары заряженных сотрудников, которым нравилось этот стайлгайд писать)
Спасибо за статью. Очень интерсно и позновательно
Самое главное - ссылку на вашу новую документацию приложить забыли ;)
https://docs.ozon.ru/styleguide/formatting/
Вы хорошо продумали стайлгайд доки, но по ощущениям у вас есть диспропорция между блоками: меню | контент | оглавление.
Меню и оглавление забрали на себя в сумме 50% полезной зоны страницы, оставив контенту остальные 50%, в следствии чего он сильно растягивается вниз. Это особенно заметно на страницах с большими таблицами, на пример "Ошибки при работе с карточками товаров" в таблице "Ошибки в характеристиках товара" (https://docs.ozon.ru/global/products/upload/moderation/errors-with-pdps/?country=CN&__rr=1#ошибки-в-характеристиках-товара). Очень мало количество символов помещается в строке ячейки, в следствии чего фразы и предложения растягиваются на несколько строк, хуже всего приходится маркированным спискам.
озон изобилуюет интересными решениями как обычно - выделить отдельного человека под актуализацию стайлгайда. приходит с десяток новых техписов, каждый с запросом на небольшие правки, под узкие кейсы, и вот у вас уже заметное расхождение от первоначальной версии. были ли уже какие-то новые решения по стайлгайду, которые сильно выбивались из той версии, которую вы имплементировали изначально?
Привет! Так как наш стайлгайд живет сравнительно недавно, пока что были только кейсы, когда его дополняли новыми пойнтами или правили мелкие опечатки. Думаю, обязательно будут такие моменты, когда новички предложат пересмотреть какие-то разделы и отдельные пойнты. В таком случае, скорее всего, мы пойдем по нашему обычному пути — обсудим это на общем созвоне и зафиксируем в гайде, если потребуется. Считаю, что наоборот круто, если это произойдет, потому что это показывает, что наша дока живет и развивается)
Очень интересная статья! Сразу тоже захотелось сделать свой стайлгайд, чтобы не надо было объяснять специалистам, что в презентации на одном слайде делать маркированный и нумерованный список, в которых первом все с маленькой буквы и с точкой, а во втором с большой и точкой с запятой. Спасибо за примеры и интересную статью.
Анна, спасибо вам большое за статью. Я как начинающий специалист выделил для себя несколько интересных нюансов, о которых раньше даже не задумывался!
Еще хотел бы задать вам пару вопросов:
Как вы стали техническим писателем, как попали на первую работу и в такую крупную компанию как озон?
Какие советы можете дать новичку, который хочет попасть в бигтех?
Есть ли у озона стажировки на технических писателей?
Пока писал вопросы, задумался - встречались ли в вашей работе нумерованные/маркированные списки, содержание которых - вопросы? Прямо как у меня в этом комментарии :). Есть ли для такого случая какие-нибудь отдельные правила?
Спасибо за комментарий! Рада, что вы нашли эту статью полезной! Отвечаю на вопросы по порядку:
При первом трудоустройстве техписом помогло наличие лингвистического образования — в проект нужен был человек со знанием английского. Остальное — везение, потому что я пришла совсем без опыта, но с желанием учиться 🙌🏻
Это банально, но смотрите на требования, которые компании постят у себя в вакансиях, и пытайтесь им соответствовать. Но даже если не соответствуете на 100%, не отчаивайтесь и все равно пробуйте — много компаний готовы брать новичков и обучать их, тот же Ozon :) Проектов, где требуются техписы, очень много, и они разнообразны — где-то нужен человек с хорошим английским, где-то — с сильным техническим бэкграундом. Узнайте ваши сильные стороны и продавайте их на собесах!
Да! У нас есть несколько крутых специалистов в команде техписов, которые когда-то приходили стажёрами. Заходите на https://job.ozon.ru/ и мониторьте — сейчас как раз открыта вакансия технического писателя :)
Интересно! Специально пошла искать по Справке для продавцов и покупателей, но нашла только один кейс, вот здесь, в раскрывашке «Что делать, если ваш магазин на Ozon заблокировали?», только это просто перечисление одного вопроса на разных языках. Вряд ли у нас будет много подобных примеров, потому что мы в документации редко используем вопросительные формулировки. Если же и пишем статьи в формате FAQ, то вопросы в них оформляем не списком, а в виде заголовков. Так что если вдруг наткнётесь в нашей Справке на такой кейс — приносите, интересно будет поглядеть!
Статья, конечно, интересная, но чувствуется, что автор слишком уж восторгается проделанной работой. Да, здорово, что вы обновили стайлгайд, но разве это не базовая задача для любой команды технических писателей? Поддерживать документы в актуальном состоянии — это не подвиг, а обязанность.
К тому же, мне кажется, что вы слишком много времени потратили на обсуждение очевидных вещей. Ну серьезно, сколько можно спорить про оформление списков или использование табов? Это все давно описано в сотнях других стайлгайдов и руководств. Зачем изобретать велосипед?
Привет! Спасибо за комментарий! Ага, этот стайлгайд мы делали маленькой группкой, гордимся им и хотим поделиться с другими! Не знаю насчет вас, но пока я ресерчила для нашего гайда, я видела не так уж много русскоязычных гайдов для технической доки — в основном для текстов интерфейсов. Так что рады пополнить число техписерских гайдов нашим!
А что касается табов, списков и прочего — вопросы языка и оформления текста бывают иногда очень комплексными и сложными, и каждая компания оформляет доку по-своему. Поэтому все эти сотни стайлгайдов и руководств, о которых вы говорите, на самом деле такие разные)
К тому же я, как техпис, знаю, что всегда интересно заглянуть, как там в этой компании доку пишут и как хинты оформляют, так что поддерживать доку — это не подвиг, а вот стайлгайд на всеобщее обозрение опубликовать — ещё какой! Надеюсь, другие команды, которые работают над своим гайдом или думают об этом, добавят наш в закладочки к сотням остальных стайлгайдов, и вдохновятся им 🙌🏻
Новый стайлгайд для технических писателей Ozon Tech: шаги, описания разделов и выводы