Профессия "Технический писатель", или "Рыцари клавиатуры"
- Автор: Михайлов Александр Владимирович
- Год: 2022
- Язык: русский
- Год: ЛЕНАНД
- ISBN: 978-5-9710-5353-8
- Жанр: Прочая компьютерная литература
Электронная книга - «Профессия "Технический писатель", или "Рыцари клавиатуры"». Краткое содержание книги:
Оценка объёма планируемой документации на самом деле достаточно проста. В первую очередь вы должны определиться, будете описывать продукт по кейсам (задачам) или функциям программы.
В первом случае нужно оценить размер одного кейса (например, внесение товара в БД), после чего проанализировать программу и посчитать количество необходимых кейсов. После этого, применяя несложную математику, можно получить время работы над документом и его размер: умножить ориентировочное время написания кейса (или его объём в знаках) на количество кейсов — вуаля, сведения получены!
Во втором случае, если документ пишется по функциям, нужно определить, сколько в программе крупных компонентов, описание которых будет отдельными разделами, затем, в свою очередь, оценить количество элементов (функций программы), составляющих собой компонент (этим элементам в документации будут посвящены главы). После этого потребуется оценить объём и затраты времени на описание каждой функции, после чего можно оценивать общее время работы путём всё того же умножения количества разделов на среднее число глав в разделе на объём или время работы с одной главой (функцией).
В качестве примера можно привести стандартную строку меню: пункты здесь станут разделами, а конкретные функции в них — главами (или пунктами, можно назвать как угодно).
После получения времени и объёма основной части документа, нужно прикинуть, сколько места и времени будет занимать сопутствующая информация — установка программы, её настройка и т. д. В кейсоориентированном варианте все это попадёт в перечень кейсов и будет учтено автоматом, при описании по функциям же нужно уделить этому отдельное внимание.
Также стоит сделать одно существенное замечание: оценка объёма здесь приведена для документа в целом, а время — лишь для его набора на клавиатуре, без всей сопутствующей работы. Подробнее о том, как оценить полные временные затраты на документ, рассказывается в следующей главе.
Объём графики для пользовательской документации рассчитывается аналогичным образом, но с оглядкой, что её должно быть не слишком много, поясняющие скриншоты нужны только в самых сложных местах, так как вы делаете её для упрощения и наглядности в сложных моментах, а не «зарисовываете» каждый шаг (за исключением инструкций для домашних пользователей — там скриншотом снабжается каждое действие, не то что функция). Также одним скриншотом окна настроек можно заменить очень много текста — достаточно будет рассказать, что сделать в этом окне, без каких-либо текстовых пояснений того, какой флажок или опция в каком месте окна находятся.
Если оценивается объём графики для аналитики, то исходить надо из двух вариантов: график или диаграмма либо заменяют текст, давая пользователю информацию только в виде изображения, либо дополняют его. Как правило, оптимальный вариант — представить все динамично изменяющие данные в виде изображения, добавив после него текстовый анализ и выводы.
При разработке руководства администратора количество необходимых скриншотов резко сокращается — как мы уже знаем, требуется показать только самые «навороченные» настройки и сложные моменты. В сложных системах можно добавить схемы, показывающие взаимодействия между компонентами, направление потоков данных и т. д.
3. Оценка времени, необходимого на разработку технического документа
Следующим важным этапом планирования работы над документом является оценка времени, которое вы затратите на его создание. Здесь нужно учитывать весь временной промежуток от старта работы до сдачи готового результата заказчику (именно готового, а не первой или последующей проверочных версий). Чтобы правильно оценить необходимые временные затраты, нужно принять во внимание и проанализировать основные факторы, влияющие на скорость разработки документа.
Как и в других элементах работы, в первую очередь нужно понять, документ для какой ЦА вы пишете. При этом речь идёт не о заказчике, а о конечном пользователе документации.
1. Если вы пишете руководство пользователя, то все элементы самой программы надо разжевать до предела, при этом вдаваться в технические нюансы её работы не нужно — достаточно показать как программа или устройство работают «снаружи», то есть с точки зрения самого пользователя. Иными словами, вы указываете, какие кнопки нажимать при необходимости совершить какое-либо действие в программе или за какой рычаг и зачем тянуть на установке.