Комментарии 10
Имхо документацию должен писать технический писатель, в идеале с поддержкой аналитика и техподдержкой (чтобы они подсветили самые проблемные места).
А вот скриншоты в зависимости от релизов, да если еще несколько языков - грусть-печалька. Пока не нашел готового инструмента, чтобы это как-то разумно делать (статичные скрины - имхо это не разумно, а какой-то привет из прошлого).
Ну и вроде есть 2 подхода к написанию мануала: канцелярский (чтобы мануал вроде бы и был, но его почти никто читать не будет) и пользователь умный, поэтому сделаем подсветку только нюансов.
Привет :) Ответ от автора "Согласна с тем, что, как минимум, документацию стоит отдать на ревью кому-то из перечисленных ролей. В отдельных случаях им даже лучше самостоятельно описать функциональность (кейсы со сложной логикой).
По поводу 2-х подходов: мы всё-таки для людей пишем, чтобы им жизнь облегчить, поэтому стараемся ёмко и по делу :)"
А вот скриншоты в зависимости от релизов, да если еще несколько языков - грусть-печалька. Пока не нашел готового инструмента, чтобы это как-то разумно делать (статичные скрины - имхо это не разумно, а какой-то привет из прошлого)
А можно чуть подробнее? про языки и статичные скрины. Языки иностранные или программирования? Вы говорите о версиях скринов в разные версиях инструкций? о единой инструкции с автоматической демонстрацией актуального скрина?
Если вопрос к автору статьи, то делимся ответом "Речь про иностранные языки и скриншоты интерфейса. Если в продукте используются какие-то сложные настройки (например, файлы конфигурации или скрипты для запуска), то лучше предоставлять их непосредственно файлами или хотя бы текстом, чтобы можно было скопировать.
Версия скринов в разных версия инструкций, всё верно.
Единую инструкцию, к сожалению, сделать не всегда можно, так как очередная версия функциональности может изменить пользовательский сценарий, и актуальные скриншоты без новых вводных будут непонятны."
Вопрос был к Младшему Брату. Языки ладно. Но замечание об устарелости статичных скринов любопытное. И непонятное. Если у клиента стоит версия №5 (условно), то и скрин ему нужен этой версии. А остальные вообще не в тему. Учитывая, что инструкции обновляются по версиям продукта вообще не вижу тут проблемы. Поэтому и спросил.
Вам за ответ спасибо.
Типа сделать ПО, где модульно все подтягивается - в зависимости от языка и также модульно редактируется, а "скриншоты" генерятся автоматически из актуальной версии ПО (гуй + язык). Под скриншотами имхо лучше понимать "миниролики" куда кликаться, чтобы получить необходимый результат, а не как сейчас у большинства: адский мануал + ролики на ютубе.
Устарелость скриншотов - это необходимость их делать под каждый новый GUI - т.е. это механическая работа, которая имхо вполне может быть автоматизирована (т.е. если уж совсем систему не переделали).
Для конечного клиента, конечно нужно показывать хелп нужной версии. Но у вас же не один клиент с одной версией ПО?
Например. есть инструмент для видео ffmpeg Многие пользуются, я в том числе. Но его man да и readme в гитхабе читать раньше было невозможно. Огромный поток бессмысленной информации для пользователя, которому надо сделать типовое простейшие действие. Например, быстренько что-то во что-то сконвертировать. Вместо это авторы долго и упорно рассказывают о своих макросах, чудесных опциях ипр. В итоге пользователь идет в гугл и где-нибудь на stkxchg находит примитивную инструкцию -i имя файла входного формат разрешение имя выходного. По своему опыту - 99% пользователей этой информации более чем достаточно. Чего ради авторы неплохого инструмента так засирают ридми совершенно не понятно. ЧСВ?! Нужны автоматизированные системы написания пользовательской документации, где будут учитываться наиболее частые случаи использования продукта. Времени мало, тратить его на чтение портянок уже никому не хочется.
Привет) Ответ от автора "Забавно, что 99% - этого, действительно, достаточно, но этот 1% 😅 бывали кейсы, когда редкая комбинация параметров клиента не учитывается системой, и это не описано нигде, поскольку никогда не возникало подобных запросов. Если это денежный клиент, то проблемы решать придётся, и неплохо бы зафиксировать на будущее её решение.
А так, безусловно всё, что можно автоматизировать, нужно автоматизировать. Вопрос бюджета и приоритетов 😉 иногда консьерж-сервис обходится существенно дешевле."
Я бы сказал, что ошибка (или "экономия") была на начальном этапе. Структура дока (оглавление) - это отображение функционала продукта, как правило. Сложная бизнес-логика, альтернативные сценарии. Все это д.было предоставлено писателю. Он этого знать не может исходно. Т.е., типа, пожалели дорогое время аналитика - а потом получили лишнюю итерацию обсуждений. Чтобы писательно мог полно и корректно написать, ему нужно предельно четко и подробно ставить задачу.
*
Чаще делают итерациями. Что-то там написал, почитал аналитик, репу почесал, замечаний набросал. И так в цикле. Но формирование структуры, бизнес-логика и неочевидная инфа о системе (которая только в голове аналитика или менеджера техподдержки) должны быть предоставлены на старте. Чтобы в голове писателя возник в главных чертах точный скелет описываемого функционала.
Привет)) Ответ от автора "Всё правильно. Обращаю внимание, что все ссылки были предоставлены на старте, как это и написано в первом абзаце в разделе «Какие возникли проблемы и почему они возникли?».
А время аналитика, действительно, пожалели. Как говорится, никогда нет времени сделать, но всегда есть время переделать 🙃"
Как не надо писать пользовательскую инструкцию