Как правильно написать руководство пользователя/HOWTO?

Напиши как попало, а потом спроси пользователя.

Благодаря wiki почти не задаюсь этим вопросом - цель how-to в том, чтобы была выполнена задача. Если после прочтения задача выполнена - how-to написано нормально.

Если нет, что-то непонятно - вносятся правка. И так do while.

При выборе между «писать how-to некрасиво» или «не писать how-to вообще» выбираю всегда первое.

Ты номер ГОСТа что ли хочешь узнать?

Ты номер ГОСТа что ли хочешь узнать?

Нет. Стандарты на технологическую и программно-техническую документацию я изучил 12 лет назад, и уже пробовал их применять. Но они работают только на очень серьёзных задачах - годы development'а с серьёзной материальной и моральной поддержкой. У меня сейчас не такие условия.
Вопрос сейчас у меня про «жизненные советы» какого-нибудь опытного технического писателя (так их нынче называют, tech writers).

zgen: Напиши как попало, а потом спроси пользователя.
Обычно так и делаю. Просто хочется как-то стандартизировать этот процесс, внести порядок.
Или, думаешь, обычная «хроника» лучше и полезнее для организма ™?

Вроде технарь, а маешься дурью, как какая-нибудь ГСМная барышня.

Просто пиши и всё. Если проблемы в сути изложения, то никакие советы не помогут.

В сути изложения проблем нету. Думаю - что почитать на ночь по этой теме. Так как ... от работы и кони дохнут ™
Нашёл красивый сайтик: Полезные ресурсы для технических писателей
и коммьюнити в LJ: http://ru-techwriters.livejournal.com/
Ещё есть весёлые советы от Чака Паланика. =)

Обычно так и делаю. Просто хочется как-то стандартизировать этот процесс, внести порядок.

Обычно когда 100500й документ пишешь, приходишь к какому-то внутреннему стандарту сам.

приходишь к какому-то внутреннему стандарту сам.

Ок. Прочитал wikipedia:Спиральная модель разработки ПО,
«Спиральная модель ориентирована на большие, дорогостоящие и сложные проекты.
Она представляет собой процесс разработки программного обеспечения, сочетающий в себе как проектирование, так и постадийное прототипирование с целью сочетания преимуществ восходящей и нисходящей концепции, делающая упор на начальные этапы жизненного цикла: анализ и проектирование. Отличительной особенностью этой модели является специальное внимание рискам, влияющим на организацию жизненного цикла. Боэм формулирует десять наиболее распространённых (по приоритетам) рисков:

1. Дефицит специалистов.
2. Нереалистичные сроки и бюджет.
3. Реализация несоответствующей функциональности.
4. Разработка неправильного пользовательского интерфейса.
5. «Золотая сервировка», перфекционизм, ненужная оптимизация и оттачивание деталей.
6. Непрекращающийся поток изменений.
7. Нехватка информации о внешних компонентах, определяющих окружение системы или вовлечённых в интеграцию.
8. Недостатки в работах, выполняемых внешними (по отношению к проекту) ресурсами.
9. Недостаточная производительность получаемой системы.
10. «Разрыв» в квалификации специалистов разных областей знаний.
»
У меня в основном 2), 3), 6,7) (так как меняется API).

P.S. Пора список must-read список делать.

Обычно когда 100500й документ пишешь,

Беда только в том, что через год-два смотришь на свои поделки - как писатель на последний том своего произведения. И думаешь - «rm-rf или всё-таки wput»?

Лучше всего - обычным русским языком. Интуитивно понятнее других приемов.

Посмотри для начала в каком стиле сделаны гайды у редхэта например, и попробуй придержаться стиля

https://access.redhat.com/knowledge/docs/Red_Hat_Enterprise_Linux/?locale=en-US

Тест-кейсы преобразовывать? Самое близкое, наверное. Сразу опишешь как что и откуда и почему.

Нет общеизвестных фишечек. Могу лишь высказать мнение, что дочь Абрама - простит наибольшее разочарование вызовет неожиданное поведение функции, особенно когда вместо возврата валидного значения она внезапно бросает исключение или возвращает nullptr/undefined. Так же просто подводные камни стоит описать, например в функцию передаётся целочисленное время - непонятно сходу, это время в секундах или в милисекундах.

вместо возврата валидного значения она внезапно бросает
исключение или возвращает nullptr/undefined.

Это да. Несколько затормаживает разработку. Впрочем, в Гугле всё есть ™

например в функцию передаётся целочисленное время -
непонятно сходу, это время в секундах или в милисекундах.

Эти вещи я загоняю в комменты //

chenger > Тест-кейсы преобразовывать?
Да, наверное так и следует сделать.
Кучку examples.

Как будто сам руководств не читал. Берешь десяток мануалов с субъективно хорошим стилем написания, и слизываешь с них структуру построения. И да, мануал!=HOWTO, последнее описывает решение нескольких наиболее типичных задач и по объему должно быть не более пяти страниц. А вот мануал разрастается на сотни - сначала лицензия и условия распространения,потом введение, потом подробное изложение HOWTO, потом описание функций в алфавитном порядке. В общес с HOWTO и начинай. Главное чтобы нарисовалась структура изложения, стилистика причесывается.

короче, хороший мануал, как минимум, должен содержать туториал и референс :)

Чорт, гениальная идея запилить HOW-TO по написанию HOW-TO!

/me убежал патентовать.

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

Пиши от души. В маркдауне.

главное чтобы нарисовалась структура изложения, стилистика причесывается.

ок
TOPT > кто будет пользоваться данной продукцией и каков уровень технической подготовки пользователя
Это да, вчера до этой же идеи дошёл. Надо с самого начала понять - кому полезен будет материал, под него и писать.