В технической и пользовательской документации часто встречаются фразы с использованием страдательного залога. Параметры там «задаются», файлы «сохраняются», а программа «запускается». Ох, опасная эта форма для строгих и однозначных описаний!
Почему же страдательный залог заставляет читателей страдать? Давайте разбираться.
Привет! Меня зовут Юрий Никулин, и я руководитель направления документирования Cloud. Сегодня расскажу, как мы перешли с документирования в Word на подход docs as code и почему в качестве языка разметки выбрали reStructuredText.
Всем привет!
Меня зовут Денисов Александр. Я работаю в компании Naumen и отвечаю за документирование и локализацию программного продукта Naumen Contact Center (NCC).
В этой статье расскажу о тех проблемах, с которыми мы сталкивались при локализации NCC на английский и немецкий языки и о том, как мы решали эти проблемы. Конечно, на сегодняшний день мы решили далеко не все свои задачи и, скорее всего, этот процесс вообще бесконечен. В статье рассматривается видение всего процесса в целом и те принципы, которым мы стараемся придерживаться или которые начинаем пробовать применять. Материал будет полезен тем, кто только начинает проектировать ПО, планирует его локализацию или уже сталкивается с проблемами, но пока не знает как их решить.
MS Word регулярно подкидывает нам «сюрпризы»: «съехавшие» скриншоты, «плывущие» таблицы, пустые страницы при печати. Эта статья о том, как мы искали замену MS Word, (спойлер — не нашли), а нашли возможность глобально улучшить наш процесс работы с документацией.
В одной из предыдущих статей мы в общих чертах рассказывали, как именно происходит процесс документирования и локализации наших продуктов.
На этот раз под катом – руководство нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу документацию для пользователей проще и понятнее (описанные приемы применяют при документировании своих продуктов Apple, Microsoft и другие компании).
Читать полностью »
Это последний доклад с шестого Гипербатона, который мы опубликуем на Хабре. Григорий Сапунов из Intento поделился подходом к оценке качества сервисов облачного машинного перевода, рассказал о результатах оценки и главных отличиях между доступными сервисами.
— Меня зовут Григорий Сапунов, я расскажу про ландшафт сервисов облачного машинного перевода. Мы измеряем этот ландшафт уже больше года, он очень динамичен и интересен.
Читать полностью »
Меня зовут Андрей Поляков, я руководитель группы документирования API и SDK в Яндексе. Сегодня я хотел бы поделиться с вами докладом, который я и моя коллега, старший разработчик документации Юлия Пивоварова, прочитали несколько недель назад на шестом Гипербатоне.
Светлана Каюшина, руководитель отдела документирования и локализации:
— Объемы программного кода в мире в последние годы сильно выросли, продолжают расти, и это влияет на работу технических писателей, которым приходит все больше задач на разработку программной документации и документирования кода. Мы не могли обойти стороной эту тему, посвятили ей целую секцию. Это три взаимосвязанных доклада, посвященных унификации разработки программной документации. Я приглашаю наших специалистов по документированию программных интерфейсов и библиотек Андрея Полякова и Юлию Пивоварову. Передаю им слово.Читать полностью »
В сентябре прошёл шестой Гипербатон — конференция Яндекса обо всём, что связано с технической документацией. Мы опубликуем несколько лекций с Гипербатона, которые, на наш взгляд, могут быть наиболее интересны читателям Хабра.
Светлана Каюшина, руководитель отдела документирования и локализации:
— Кажется, в мире уже не осталось людей, которые переводят вручную. Сегодня мы хотим поговорить об инструментах и подходах, которые помогают компаниям организовывать эффективный процесс локализации, а переводчикам облегчают решение их повседневных задач. Сегодня мы поговорим о машинном переводе, об оценке эффективности машинных движков и о системах автоматизированного перевода для переводчиков.
Начнем с доклада наших коллег. Приглашаю Ирину Рыбникову и Анастасию Пономарёву — они расскажут об опыте Яндекса по внедрению машинного перевода в наши процессы локализации.Читать полностью »
Написание технического документа — трудное дело. Чтение плохо написанного технического документа является более трудным и, вероятно, более болезненным делом, чем его написание. Требуется большая работа, чтобы создать ясное, точное, интересное техническое описание. Поэтому, чтобы сделать жизнь хоть немного проще для всех участвующих сторон, я хотел бы поделиться с вами семью правилами, которым я следую, создавая техническую документацию.
Эти правила — не моё собственное изобретение. Скорее, я просто сформулировал их из того опыта, который появился благодаря общению со многими талантливыми техническими и литературными редакторами за более чем десять лет работы. Всё, что я понял в этом деле, сформировалось потому, что другие показали мне путь. У меня не находится достаточно слов, чтобы выразить им в полной мере мою благодарность.
Надеюсь, после прочтения этой статьи в вашем арсенале появятся некоторые новые инструменты, которые помогут вам создавать технические документы на новом уровне качества: более ясные, более привлекательные, менее путанные и намного более интересные для чтения. Также я добавил — без всяких каких-либо дополнительных требований к вам, как потребителю, бонус в конце статьи: описание процесса, используемого мною для создания технического описания.
Итак — эти 7 правил:
Буквально на днях на Geektimes публиковалась новость о том, что «из-за экономических проблем книжный магазин Manuals Plus в штате Мэриленд вынужден закрыться. В понедельник 17 августа они выкинут всю свою коллекцию мануалов. Это огромная коллекция, которая содержит справочные руководства к разнообразной технике с 30-х годов прошлого века». Несколько энтузиастов узнали о проблеме, и решили привлечь добровольцев к спасению всей этой информации.
Был дан клич в социальные сети, и, к удивлению инициаторов, нашлось несколько десятков человек, которые изъявили желание помочь. С утра Джейсон Скотт (Jason Scott), автор идеи по спасению мануалов, уже был в магазине в 8 утра. С собой он привез 400 коробок (их подарил один из тех, кто решил помочь проекту) для перевозки материалов. К этому же магазину подошли и волонтеры — около 20 человек. Работа началась.
Читать полностью »
