Хабр Курсы для всех
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 17
Есть один большой производитель ПО, который почему-то практически не вставляет изображения в документацию. Ненавижу его за это. Всё пишет словами, хоть и с пунктами и подпунктами, как вы говорите. Всё гадаю почему он так делает. Варианты:
1. Документация многоязычная. Изображение всегда содержит буквы, которые должны быть переведены. Но средство перевода не имеет возможностей управления изображениями, как объектами которые зависят от языка.
Кстати, в данной статье не переведена картинка «Рисунок номер один». Мне кажется это не айс для статьи.
2. Изображение может содержать скриншоты интерфейсов программных средств, а они зависят от локализации, операционной системы, темы оформления итд итп.
Кстати, была у нас тут была задача у технописателей перешотить скриншоты в теме оформления, которая по умолчанию включена у пользователей.
А у технописателей обычно была другая.
3. Процесс перевода устроен так, что сначала разрабатывается исходная документация, потом отдается переводчику. Переводчик не имеет доступа к приложению и не может переснять скриншот на нужном ему языке. Не вставлять изображения — один из способов не создавать проблем.
Кстати, именно поэтому я некоторых случаях избегал вставлять таблицы к документам по ГОСТу (продолжение таблицы будь оно проклято, ругался с проверяющими — без толку).
4. По моему мнению, нельзя пользоваться вордом для писания документации.
Многие вики-системы имеют бедные инструменты по работе с таблицами и рисунками.
И от этого качество документации в итоге тоже страдает.
Кстати, в документации от этого разработчика ПО и таблиц меньше чем хотелось бы. Всё больше списки.
1. Документация многоязычная. Изображение всегда содержит буквы, которые должны быть переведены. Но средство перевода не имеет возможностей управления изображениями, как объектами которые зависят от языка.
Кстати, в данной статье не переведена картинка «Рисунок номер один». Мне кажется это не айс для статьи.
2. Изображение может содержать скриншоты интерфейсов программных средств, а они зависят от локализации, операционной системы, темы оформления итд итп.
Кстати, была у нас тут была задача у технописателей перешотить скриншоты в теме оформления, которая по умолчанию включена у пользователей.
А у технописателей обычно была другая.
3. Процесс перевода устроен так, что сначала разрабатывается исходная документация, потом отдается переводчику. Переводчик не имеет доступа к приложению и не может переснять скриншот на нужном ему языке. Не вставлять изображения — один из способов не создавать проблем.
Кстати, именно поэтому я некоторых случаях избегал вставлять таблицы к документам по ГОСТу (продолжение таблицы будь оно проклято, ругался с проверяющими — без толку).
4. По моему мнению, нельзя пользоваться вордом для писания документации.
Многие вики-системы имеют бедные инструменты по работе с таблицами и рисунками.
И от этого качество документации в итоге тоже страдает.
Кстати, в документации от этого разработчика ПО и таблиц меньше чем хотелось бы. Всё больше списки.
Есть один большой производитель ПО, который почему-то практически не вставляет изображения в документацию. Ненавижу его за это. Всё пишет словами, хоть и с пунктами и подпунктами, как вы говорите. Всё гадаю почему он так делает.
Ответ очень простой — ему ммм… безразлично, качество документации, производитель Большой — от него никто никуда не денется. Вот если бы это был стартап, особенно с существенными вложениями, то и таблицы бы переделывали и скриншоты бы переснимали и даже кейсы бы переписывали с учётом страны/языка.
Не хочу оправдывать больших производителей с большими продуктами, но поддерживать десятки и сотни тысяч документов с локализуемыми картинками — то ещё удовольствие.
Если документов менее десятка тысяч — ещё могу себе представить.
Если документов менее десятка тысяч — ещё могу себе представить.
Работать вообще не легко. Если у компании есть ресурсы на производство N продуктов с документацией, то есть и ресурсы на её нормальную локализацию.
Почему нельзя иллюстрации (не скриншоты) делать векторными? Тогда и текст в них можно автоматически заменять, и другие плюсы будут тоже.
Вы абсолютно правы.
Но, к примеру, у меня 99% всех картинок — это скриншоты, а не схемы.
Для того, чтобы поддерживать это добро в актуальном состоянии, мы пользуемся обратной связью и регулярно просматриваем свои документы (см. комментарий ниже).
В некоторых случаях можно заранее предугадать, что скриншот устареет через некоторое время, например, если в скриншоте виден номер версии продукта. Такие скриншоты мы помечаем специальным флагом. Перед выпуском новой версии технический писатель выбирает из БД те картинки, которые содержат устаревший номер версии и снимает эти картинки по-новой.
Но, к примеру, у меня 99% всех картинок — это скриншоты, а не схемы.
Для того, чтобы поддерживать это добро в актуальном состоянии, мы пользуемся обратной связью и регулярно просматриваем свои документы (см. комментарий ниже).
В некоторых случаях можно заранее предугадать, что скриншот устареет через некоторое время, например, если в скриншоте виден номер версии продукта. Такие скриншоты мы помечаем специальным флагом. Перед выпуском новой версии технический писатель выбирает из БД те картинки, которые содержат устаревший номер версии и снимает эти картинки по-новой.
Интерфейс часто меняется. Проще переписать текст, чем выискивать и заменять все скриншоты.
Спасибо! Статья оказалась полезной. Наличие структуры и подписей к иллюстрациям было для меня достаточно очевидным, а вот про два предложения на уровень взял на заметку.
Хотя самое сложное — это седьмое правило: перерабатывать выстраданный текст ещё два раза тяжело себя заставить :)
Хотя самое сложное — это седьмое правило: перерабатывать выстраданный текст ещё два раза тяжело себя заставить :)
Дополню. С моей точки зрения правилами хорошей документации должны быть:
- Обязательное наличие канала обратной связи для улучшения документации.
- Большое количество примеров наиболее распространенных use-case'ов.
- Документацию регулярно нужно перечитывать (одним сотрудником раз в месяц, чтобы избежать замыленности внимания). Возникающие вопросы тут же пояснять.
- Качественные цветные графики, иллюстрации. С этим чаще всего бывают проблемы. Взгляните хотя бы вот на этот график. Он ужасен.
- Полная воспроизводимость руководства к действиям. За этим тоже нужно регулярно следить.
Я эту тему уже затрагивал здесь.
Добавлю ещё одно, крайне на мой взгляд, важное правило (получилось в стиле zen):
Лучшая документация — ненужная документация
Смысл в том, что с большинстве случаев пользователь должен получать решения без обращения к документации, в идеале просто нажимать кнопку «сделать хорошо».
Конечно, это требование не столько к документации, сколько к самому продукту, но здесь документация играет роль своеобразного индикатора — чем чаще она требуется, тем сложнее приложение (в смысле «усложнено»).
Причём особенно играет этот фактор на этапе вхождения нового пользователя.
Лучшая документация — ненужная документация
Смысл в том, что с большинстве случаев пользователь должен получать решения без обращения к документации, в идеале просто нажимать кнопку «сделать хорошо».
Конечно, это требование не столько к документации, сколько к самому продукту, но здесь документация играет роль своеобразного индикатора — чем чаще она требуется, тем сложнее приложение (в смысле «усложнено»).
Причём особенно играет этот фактор на этапе вхождения нового пользователя.
Документация бывает очень разная. Если вы имеете дело с библиотеками, компонентами и их API, то документация нужна и без нее не жить.
Однозначно согласен! Но в большинстве «обычных» случаев — чем меньше дока — тем лучше.
Ну почему «обычных», почти во всех. Качество документации выше когда:
То есть, можно перефразировать: «чем меньше дока — тем лучше, если это не наносит вред её читаемости и полноте».
- выше качество текста (читаемость, понятность, однозначность);
- текст максимально покрывает всю описываемую функциональность, процессы, факты;
- оба первых пункта выполнены с минимальным количеством текста.
То есть, можно перефразировать: «чем меньше дока — тем лучше, если это не наносит вред её читаемости и полноте».
Спасибо! Очень полезная статья. Взял на «вооружение».
Хорошо, когда не понравилась документация и клёп на «Далее» на свою страницу на мордокниге. А когда перед тобой документация, к тому же всего лишь одна из, на более чем 900 страниц, где каждая строка примерно следующее:
This assignedEntity MAY contain zero or one [0..1] code, which SHOULD be selected from ValueSet Healthcare Provider Taxonomy (HIPAA) urn:oid:2.16.840.1.114222.4.11.1066 DYNAMIC (CONF:1198-32173).
И хоть ты всю доку комиксами зарисуй, толку от них в этом контексте мало.
This assignedEntity MAY contain zero or one [0..1] code, which SHOULD be selected from ValueSet Healthcare Provider Taxonomy (HIPAA) urn:oid:2.16.840.1.114222.4.11.1066 DYNAMIC (CONF:1198-32173).
И хоть ты всю доку комиксами зарисуй, толку от них в этом контексте мало.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
7 правил написания технической документации мирового класса