Какие критерии вы используете, когда ставите или принимаете задачу на технический документ?
public poll

Знаю и использую эти критерии – 9
👍👍👍👍👍👍👍 60%
@Elaneor, @solntseN, @SoNiQQQue, @Nick_Volynkin, @Lananovikova, @kipkaev, @annacraneo, Алена, Sagi

Теперь знаю и буду использовать – 5
👍👍👍👍 33%
@Andreichernov, @Altenrion, @IharReznichenka, @Lytkini, @dr_heart

Использую другие критерии, расскажу в @docsascode – 1
👍 7%
@mnmlsniper

Не буду использовать (интересно, почему → @docsascode)
▫️ 0%

👥 15 people voted so far.

Илья Бирман критикует нумерованный список с причинами отказа:

Сайт перечисляет причины, по которым деньги пользователя до него не дошли. Из-за использования списка с точками кажется, что случились все эти беды. Если заменить список на вариант со скобками 1) 2) 3) 4) 5), будет читаться чуть легче. Никто не знает, почему так, но список с точками скорее воспринимается как элементы, соединённые союзом «и», а со скобками — союзом «или».

​​Думаю, что нужно пойти дальше и сменить список на маркированный. Номера подразумевают порядок. Маркеры — это выбор независимых вариантов. Смотрите, что получается:

​​Как правильно закодить локализуемые строки

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

Общий принцип номер один: предложения переводятся целиком, поэтому и в коде они должны быть целиком.

Например, в интерфейсе есть такая строка:

Nick's account is suspended

Здесь есть имя пользователя, его нужно подставить в шаблон. Наивный программист напишет так:

user + "'s account was suspended"

Переводчик получит только строку в кавычках и перведёт, как сможет:

Nick учётная запись заблокирована

Это звучит ужасно, поэтому переводчик может поменять смысл в угоду грамматике:

Nick, ваша учётная запись заблокирована

Это ещё хуже, потому что текст адресован не владельцу учётной записи.

Как правильно

В коде всё предложение должно быть одной строкой-шаблоном:

"{name}'s account is suspended".format(name=user)

Теперь переводчик сможет поставить переменную в нужное место:

— "Учётная запись {name} заблокирована"
— "Cuirtear cuntas {name} ar fionraí"
— "គណនីរបស់ {name} ត្រូវបានផ្អាក"


Одно предложение = одна строка-шаблон

#l10n_docops

---

Если вы давно это знали или просто хорошо разбираетесь в локализации — заходите в чат @docsascode, поделитесь опытом и болью.

На фото — доска после обсуждения на митапе. На ней есть кусочки двух ещё не опубликованных постов. 😉

Технический переводчик для хардкорных текстов


Раньше я участвовал в переводе ежемесячных постов про GitLab для Хабра, это было очень интересно и я прокачался в переводах. Вот мой любимый перевод: GitLab Flow

Теперь времени на это не хватает и я только заглядываю в качестве технического редактора и subject matter expert.

А в nadmosq.ru нужны новые технические переводчики. Ребята занимаются настоящими техническими текстами — программирование и девопс, никаких обзоров техники или прочего треша.

Если вам это интересно — напишите мне (@Nick_Volynkin), расскажу о деталях. Знаете хороших переводчиков? Пожалуйста, свяжите нас.

#l10n_docops

Нашёл отличный канал про тексты в интерфейсах, рекомендую: @tinywordsmakemagic

Вот ещё одна иллюстрация ошибки, утекающей в интерфейс (см. www.tg-me.com/docops/57)

Когда эксперты Тотального диктанта, преподаватель Института филологии, журналистики и межкультурной коммуникации Южного федерального университета и IT-координатор не подумали о тексте ошибки

Привет всем, кто тащит легаси в светлое будущее!

Александр Парень рассказывает, как сделать из старого Confluence Server новый Confluence Cloud: http://telegra.ph/Migriruem-kontent-s-Confluence-41-na-oblako-07-26

Вот ещё его доклад о том, как готовить Confluence: https://youtu.be/TLOvJAb-E2Y

​​Задача номер 1

Я хочу сыграть с вами в одну игру.

Вот три абзаца текста из очередного релизного поста GitLab 11.1. Как вы считаете, можно ли в них что-то улучшить? Есть ли в них общие ошибки?

Первый абзац не связан по смыслу со вторым и третьим. Я поставил их рядом ради иллюстрации.
Если вам нужен контекст, вот пост целиком: GitLab 11.1 released with Security Dashboards and enhanced code search.

Напишите ответ мне — @Nick_Volynkin. Тех, кто раньше всех найдёт ошибки, я публично похвалю и/или угощу чашкой кофе, когда буду с вами в одном городе.

#docops_challenge

​​Консистентность

Наш мозг учится узнавать объекты по их внешним признакам. Мы понимаем знакомые буквы в незнакомых шрифтах, узнаём номера телефонов и адреса электропочты, отличаем кран с горячей водой от крана с холодной.

Если объект выглядит или называется совсем не так, как мы привыкли, мы тратим время и силы на узнавание. Но мы хотим, чтобы читатель понимал нас как можно скорее и легче.

Вывод: Однородные объекты должны выглядеть одинаково, разные — по-разному.

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

— Элементы интерфейса выделены внутристрочным кодом, полужирным или никак не выделены.
— Названия панелей могут быть с заглавной или строчной буквы: Security Dashboard, performance dashboard.

Неконсистентное оформление первым заметил тестировщик @oneumyvakin, это было ещё вчера вечером. А сегодня он начал работать в Plesk. Совпадение? Да, совпадение.

Неконсистентный стиль в названиях дашбордов первым заметил @arvikon в чате @docsascode.

На фото мы с Олегом @oneumyvakin на кухне Plesk, у него в руках обещанный мной кофе.

А текст в задаче неконсистентен не только по оформлению. О второй ошибке напишу завтра.

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

Дмитрий Лишик, Системный подход к техническим коммуникациям.

https://youtu.be/g_YjFnkcjgo

Консистентность-2

Снова про задачу о неконсистентном тексте. Смотрите, какая штука происходит с кнопками в интерфейсе. Их можно:

— нажимать: «Clicking on Metrics...»
— или выбирать: «then select Monitorings button»

Фактической разницы нет. Просто одно и то же нажатие на кнопку в соседних абзацах называется по-разному.

Во втором и третьем абзаце есть такие сущности:

— Рабочие окружения (environments): production и другие.
— Метрики производительности приложения, которое развёрнуто в конкретном окружении (application performance metrics).

Всё идёт хорошо, пока в последнем предложении не появляются «production metrics». Автор текста взял и сделал новый термин из двух старых. Что этот новый термин обозначает? Кажется, что это метрики приложения, развёрнутого в окружении с именем production, но полной уверенности у меня нет.

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

Чтобы такого не было, используйте термины консистентно:

Для каждой сущности — свой термин. Каждый термин — только для одной сущности.

Неконсистентное использование click-select первым заметил @glu0n. Ещё несколько человек писали мне об этих и других проблемах текста. Кое-кто сразу переписал текст в довольно приятном и понятном стиле. Спасибо всем, кто откликнулся! Очень ценю ваш вклад.

Как выстроить разработку внутренней документации

Игорь @i_tsupko спрашивает в чате @docsascode:

Проблема: есть пара-тройка человек, которые пополняют внутреннюю базу знаний. И каждый тянет одеяло на себя, не могут договориться о том как структурировать доки, как делать меню, навигацию и прочее.

Как договориться? В программировании для этого есть фреймворки и паттерны. А с русским языком как быть? Он ж не компилируется и автотесты не напишешь.

Что важно в документации:

— Структура и читаемость — чтобы юзер мог это брать и юзать на своем уровне компетенций.
— Ненагруженный, неформальный язык и минимум формализма.
— Важнее наличие хотя бы паршивой, верхнеуровневой, но хорошо структурированной доки (а-ля вот эта задача решается примерно по таким шагам, копать туды) но раньше, чем хорошо проработанной, но позже.
— Важно, чтобы дока внедрялась и юзалась. Важнее всего и даже текста.

У вас тоже это болит? Знаете решение? Приходите в @docsascode, обсудим.

Внутренняя документация с картинками и разграничением доступа

Дарья (@Greenochre, канал @pmwithloveandsqualor) ищет инструмент для внутренней документации:

В чем уместно вести внутреннюю документацию для анимационной студии? Джиры и конфлюэнса у нас нет; кода нет тоже))

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

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

Что есть лучше гуглдоков, желательно бесплатное и с аналогичной регулировкой уровней доступа?

Помогите Дарье найти, в чём писать документацию!

Как обычно, приглашаю поделиться идеями в www.tg-me.com/docsascode.

Публикация из AsciiDoc в PDF по ГОСТ

Компания Course сдаёт отчётную документацию в PDF со строгими требованиями к оформлению, потому что работает с банками и государственными заказчиками. При этом:

— Документацию разрабатывают в формате разметки AsciiDoc, со всеми преимуществами подхода «документация как код»: пишут в удобном редакторе, версионируют в Git, легко объединяют изменения от нескольких авторов. (Попробуйте-ка заняться этим в Word.)

— Большáя часть документации автоматически генерируется из программного кода: структура БД, описание REST API сервисов, частично ПМИ и результаты автоматизированного тестирования по ПМИ.

Как получилось совместить ГОСТ и документацию как код? Николай Поташников, автор той самой статьи про диаграммы как код в PlantUML, разработал шаблон для публикации из AsciiDoc в PDF со всеми требованиями к оформлению.

Вот исходный код и документация к шаблону: github.com/CourseOrchestra/course-doc

Николай хочет дорабатывать и улучшать этот шаблон, чтобы и другие компании могли отказаться от неудобных редакторов в пользу AsciiDoc. Нужна обратная связь. Если вы используете AsciiDoc — пожалуйста, протестируйте шаблон и напишите о результатах в чат @docsascode, либо автору на @nmpotashnikoff или [email protected].

#docops_toolkit #docops_markups #docops_gost

Deboogging Loceleezeshoon!

Копаюсь в Translate Toolkit, нашёл инструмент для дебага локализации, он «понарошку» переводит строки. Среди вариантов есть псевдо-шведский, вдохновлённый персонажем Маппет-шоу Swedish Chef. Вот что получается:

Introdoocteeon

This gooide-a describes how to troonsffer hosted content to Plesk Oonyx using Plesk Migretor. Bork Bork Bork! It is intended for hosting idministretors who perfform migreshoon to serfers mooneged fia Plesk. Bork Bork Bork!

Whet Deta Ire-a Troonsfferred

Plesk Migretor troonsffers serfice-a ploons, soobscripshoons wit ill issocieted domeins, und websites wit content (sooch is files, meil, detebeses, und so oon). Reseller und coostomer iccooonts zeet do not hefe-a uny domeins ire-a not troonsfferred. Bork Bork Bork! Zee-a settings ooff Plesk serfices, sooch is instelled PHP hoondlers, Feeel2Boon settings, ModSecoority settings, foorooell settings, und so oon ire-a not troonsfferred. Bork Bork Bork!

Сравните с оригиналом: Plesk Migration Guide – Introduction.

Дебаггер работает с файлами в формате GNU Gettext (.po):

podebug --rewrite chef source.po chef.po

#docops_l10n

​​Как подумать и написать обо всём, что важно

Представьте, что мы с вами придумываем новую фичу и пишем о ней документ (vision, SRS, ТЗ). Именно по этому документу дизайнеры придумают интерфейс, разработчики напишут код, а тестировщики проверят, всё ли получилось правильно.

Нам нужно обдумать и описать несколько аспектов фичи: интерфейс, безопасность, GDPR и другие. Держать всё это в голове довольно сложно.

Кажется, что задачу можно упростить шаблоном документа с заголовками секций про каждый аспект. Но бывает, что для фичи X неактуален аспект Y. Например, она не меняет интерфейс. Что тогда делать с заголовком из шаблона?

✘ Удалить заголовок. Читатель не поймёт, забыл автор про это написать или сознательно убрал.
✘ Оставить заголовок, ничего не писать. Так точно будет впечатление, что автор забыл.
✘ Оставить заголовок и написать «Это неприменимо или не имеет значения для этой фичи». Это засоряет документ и усложняет работу читателя.

Все варианты плохи. Ещё сложнее делегировать разработку фич и написание таких документов. Тогда мы сами становимся непонимающими читателями.

Сергей Егоров, руководитель program manager'ов в Plesk, поделился решением:

В конец документа добавляем табличку-чеклист со списком аспектов. В ней ПМ отмечает каждый аспект: «Описано в документе» или «Неприменимо». Если неприменимо — заголовок можно убирать. Если ничего не отмечено, значит ПМ ещё это не проработал.

✔ Отмечать в отдельном чеклисте: аспект описан / неприменим для этой фичи / конь не валялся.

#docops_workflow

Если вам нравится продумывать новые фичи и развивать продукты, в Plesk есть вакансия program manager'а в команду к Сергею Егорову, эксперту из прошлого поста про шаблон-чеклист документа.

Вопросы про вакансию и компанию в целом можно задавать мне на @Nick_Volynkin или [email protected].