BoatmansHome: ДокументарныеТехнологии/ЧастыеПроблемыДокументирования ...

Boatmans Home Start | Каталог | Изменения | Комментарии | Пользователи | Регистрация | Вход  Пароль:  
Данные материалы созданы для размещения на сайте boatmanshome.ru. Во всех случаях, кроме явно оговоренных в теле материала, автор и обладатель исключительного права - Нужненко Сергей Александрович. Во всех случаях, кроме явно оговоренных в теле материала, для данных материалов разрешено размещение ссылок и цитирование, а так же воспроизведение в личных и учебных целях. Без согласования с правообладателем запрещается для данных материалов или любой части использование в коммерческих целях, а так же распространение, публичный показ, импорт с целью распространения, прокат, переработка, сообщение для всеобщего сведения.
 

ЭТОТ ТЕКСТ ПЕРЕЕХАЛ НА asbok.ru – http://asbok.ru/wacko/DokumentarnyeTexnologii/ChastyeProblemyDokumentirovanija
!! Актуальная версия там

Частые проблемы технического текста


Оглавление


В очередной раз вычитывая толстый документ решил записать список часто встречающихся ошибок с пояснениями, какие проблемы это порождает и как лучше делать при создании документов.
Можно так же использовать, как контрольный список для проверки документа.


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


Что еще почитать по теме:


Сейчас этот текст — заготовка, куда я постепенно занесу все, что вспомню и все, что коллеги мне подскажут. Так что обсуждение приветствуется.
В целом никаких секретов не излагается, задача – собрать максимальное количество советов в одном месте.


Обсуждение идет здесь: https://www.facebook.com/groups/Analiz.v.IT/permalink/1145207925497979/

Благодарности и соавторство


Коллеги, которые подсказали, что добавить в памятку:


благодарю за поддержку:

I. Документ в целом

0. Отсутствие сострадания к читателю


Представьте себя и так загруженного ИТ-инженера на стороне заказчика, которому в качестве общественной нагрузки выдали роль представителя заказчика в вашем проекте.
Вот он ближе к 10 вечера заваривает крепкий чай, открывает ваш документ (например, ТЗ или пояснительную записку к техпроекту) и начинает слезящимися глазами читать, от усталости, путая все, что можно перепутать, очитываясь везде, где только можно и теряя нить на каждой шероховатости документа.


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


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

1. Нет титульного листа и/или карточки документа с названием, автором, статусом


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


Автор: иногда проще позвонить и задать пару вопросов «что имеется ввиду», чем вступать в длинную переписку. Образованные люди, которые не понимают, что написано могут почувствовать себя сильно неловко. Про негатив я уже писал.


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

2. Игнорируется основное назначение любого документа


Кто-то прочитавший предыдущие пояснения скажет: «зачем вы нам читаете курс по бытовой психологии про негатив и полемический забор?».
Поясняю: документ – носитель информации, основное назначение которой изменить поведение и/или состояние получателя. Любой нормальный человек имеет массу фильтров, предотвращающих нежелательное влияние извне. Один из самых мощных фильтров – это недоверие и плохое отношение к автору.


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

3. Введение отсутствует


В начале документа желательно сказать пару слов о его назначении и области применения: какую информацию он содержит, кто и в рамках какой деятельности должен его применять.
Удобно перед созданием документа проанализировать его варианты использования в том же смысле и стиле, что и варианты использования автоматизированной сили бизнес-системы. И о результатах этого анализа сообщить читателю. Это сразу дает понимание читающему, из какой роли он должен читать и снимает массу недоразумений.

4. Пояснения временного назначения документа отсутствуют


В процессе разработки промежуточные редакции документа предназначены не для того же, для чего окончательный документ.
Например, вообще это ТЗ на АС – контракт на построение системы, но данная редакция предназначена для ревью внутри рабочей группы по существу предлагаемых решений с точки зрения их полноты и непротиворечивости (форматирование и орфографию не смотрим).
Или наоборот: документ содержит согласованные по составу и содержанию решения, сейчас проверяем орфографию, непротиворечивость и понятность формулировок и правила оформления.
Такие пояснения сразу отрезают много замечаний и экономят силы, как читателей, так и авторов. Причем, если в первом примере мы просто получаем немного лишней работы, то во втором примере есть риск уехать на еще пару кругов обсуждения существа проектных решений.

5. Нет глоссария и расшифровки обозначений


Пояснение терминов и сокращений должно быть.
Что включать:


Не надо включать определения из словаря или википедии. То есть определения должны быть построены не в общечеловеческом контексте, а в контексте данного проекта/системы/процесса/организации и т.п.


То есть не правильно делать так:
Сервер приложений (англ. application server) — это программная платформа (фреймворк), предназначенная для эффективного исполнения процедур (программ, скриптов), на которых построены приложения. Сервер приложений действует как набор компонентов, доступных разработчику программного обеспечения через API (Интерфейс прикладного программирования), определённый самой платформой.
Для веб-приложений основная задача компонентов сервера — обеспечивать создание динамических страниц. Однако современные серверы приложений включают в себя и поддержку кластеризации, повышенную отказоустойчивость, балансировку нагрузки, позволяя таким образом разработчикам сфокусироваться только на реализации бизнес-логики.
см. https://ru.wikipedia.org/wiki/%D0%A1%D0%B5%D1%80%D0%B2%D0%B5%D1%80_%D0%BF%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D0%B9


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

6. Не указаны связи документа


Наиболее актуально для больших систем/документов.
Документ никогда не висит в воздухе. У него есть предшественники, содержащие исходные данные и решения, есть документы, входящие в один пакет с данным документом, есть планы, какие документы будут разрабатываться на основе данного документа.
Все это имеет смысл указать.


Например, если разрабатывается ЧТЗ (частное техническое задание), можно указать ссылки на вышестоящее техническое задание и смежные ЧТЗ по соседним подсистемам. Так же можно сразу сказать, какие документы техпроекта будут разработаны на основе данного ЧТЗ.


Что будет, если этого не сделать, причем сразу – до начала написания документа:

7. Не описано соотношение рамок документа и рамок продукта/системы


Если документ является частичными требованиями, желательно явно указать какой набор документов составляет полные требования к системе/продукту.
Например, частное техническое задание должно содержать ссылку на техническое задание с указанием, что в сумме ЧТЗ и ТЗ дают полный набор требований к подсистеме.
Если так не сделать, в реализацию могут быть спущены неполные требования.


То же относится и к регламентам и другим требованиям.

8. Заимствование без смены реквизитов


Часто документы пишутся не с нуля, а взяв за основу предыдущий аналогичный документ. И типичная ошибка в этом случае – не изменить колонтитул, не проверить список терминов и сокращений и даже не изменить название документа.


Итоги печальны. Во-первых все видят «плагиат», но это ладно. Во-вторых резко падает доверие к изложенным решениям: если даже название и колонтитул с ошибкой, то сами решения нуждаются в 100%-ной перепроверке.
Хороший способ заимствования документа – в начале выделить все и покрасить желтым (или каким -то другим) цветовыделителем. Отдельно исправить колонтитул и внутренние атрибуты документа (автор, название и т.п.), если они используются. Затем исправить титульный лист, потом введение, если оно есть. И потом только идти по тексту, снимая желтое цветовыдление на проверенных участках текста.

9. Глоссарии в рамках одного пакета документов противоречивы

Для документов, относящихся к одной системе (или пакету документов) желательно иметь единый глоссарий (в смысле единых терминов, так как один документ на систему может не получиться). Чтобы и термины и их определения в разных документах системы не расходились. И чтобы сокращения имели единое значение. Например, ГК – либо главная книга либо госконтракт во всей системе.

10. Написание документа без шаблона или хотя бы состава


На самом деле это два пункта:


11. Нет оглавления

ЗАПОЛНИТЬ

II. Страницы

1. Страницы не пронумерованы


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

2. Колонтитулы не информативны


Представим себе ситуацию: на столе лежит 5 открытых документов, причем, все только что отпечатаны и не скреплены, время к девяти вечера, рабочий день начался в десять утра. Обычная ситуация для инженера или, например, процессного менеджера. Чтобы было легче понимать, куда мы сейчас смотрим, в колонтитул просится название (и код) документа, для очень толстых документов – название раздела.
Если идет мучительное согласование с большим количеством подписей и километровой сводкой замечаний, то в колонтитул удобно вынести номер редакции и/или ее текущий статус.
При работе в электронном виде эти вопросы немного смягчаются, однако надо помнить о том, что документ могут напечатать и не скрепить. Или напечатать пять разных документов и потом долго чертыхаться, собирая пачки для сшивки.

III. Абзацы


1. Абзацы текста не пронумерованы


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


Кроме нумерации абзацам можно присваивать более сложные коды типа “FR0012”. Это чаще используется, если мастер-данные для, например, требований лежат в системе управления требованиями, а документ был сгенерирован.
Минус такого подхода в том, что в отличие от нумерации, коды не обязаны идти по порядку и без разрывов в номерах, что затрудняет ориентирование в документе. Кроме этого поиск по коду в общем случае требует электронного экземпляра документа.


Существует мнение, что документ в электронном виде можно положить в среду с групповым редактированием и комментированием и получать замечания и правки от ревьюверов прямо там. Однако выбор инструментов и процессов для работы группы с документом – это тема для отдельного большого разговора. Иногда инструменты типа google docs идеальны для работы над документом, в других случаях они совсем не подходят.

2. Содержательный текст в не листьевых абзацах


Пример:
56. Заголовок раздела
Текст 1
56.1. Текст 2
56.2. Текст 3


Проблема в том, что на Текст 1 невозможно сослаться, так как п.56. – это раздел в целом, то есть Текст 1 и пп.56.1., 56.2.

3. Не текстовая разметка в чистовике


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


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


В остальном цветовыделитель для разметки документа в рабочем режиме (не в чистовике) – хороший инструмент.


IV. Таблицы

1. Не включено повторение заголовка таблице на каждой странице


Очень легко перепутать колонки. Сложно ссылаться.

2. Колонки не пронумерованы (скорее хинт, чем проблема)


Нумерация колонок позволяет давать им длинные осмысленные названия, отражающие семантику записанной информации и, при этом, ссылаться на колонки с удобством.
Пример длинного названия: «Объем, Гб (к вехе №5 «Очередь 3 в промышленной эксплуатации»), не более». При нумерации колонок сюда легко сослаться.
Я и сам их редко нумерую, однако иногда бывает очень удобно.

3. Включен перенос ячеек на следующую страницу


На следующей странице не виден номер строки, легко потеряться, куда конкретно мы смотрим.

4. Строки не пронумерованы


В большинстве случаев – это за пределами добра и зла. На строку невозможно сослаться, затруднено ориентирование в длинной таблице.
Иногда нумерация не нужна – очень мало строк, очень короткие ключи строк в другой колонке.

5. Название таблицы плохо выделено


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


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

6. Пустые ячейки вместо прочерков


В таблице не должно быть пустых ячеек. Если здесь не должно быть ничего написано, необходимо поставить прочерк. Программисты меня поймут- это, как разница между 0 и null.
Это важно, так как при работе с таблицами чаще всего идет рутинное заполнение ячеек похожими данными в процессе принятия решений, и часто это происходит в несколько подходов. Если прочерк стоит — это значит, что здесь были проектировщики и решили ничего не писать. Если прочерка нет, значит сюда еще никто не доходил и решение не было принято.
В итоге мы ставим прочерк во-первых для того, чтобы больше не думать о данной ячейке, а во-вторых, чтобы читатель не думал, что мы забыли заполнить ячейку.

7. Слияние ячеек


Если есть вероятность, что таблица будет копироваться в excel для обработки, слияние недопустимо. Сразу перестают работать фильтры, сортировка и много других интересных вещей.
Групповая вставка строк и столбцов тоже могут повести себя странно, если есть слияние ячеек.
Так что желательно сливать ячейки только если очень нужно и только на стадии финальной полировки документа.

8. Таблицы не пронумерованы


Я сам не всегда делаю то, что пишу. И сам часто получаю от этого проблемы.
По хорошему, каждая таблица должна иметь номер и название, поясняющее семантику представленных данных.
Более того, из текста должна быть ссылка на таблицу. И более того, эта ссылка должна быть в тексте до таблицы.


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


Было:
5. Функции подсистемы ПС05
ТАБЛИЦА


Стало:
5.Требования к функциям подсистемы ПС05
5.1. Все функции ПС05 должны ...
5.2. В режиме ... функции ПС05 должны ...
ТАБЛИЦА


Формально семантика данных в таблице утеряна.


Должно быть так:
5.1. Состав функций ПС05 и требования к ним указаны в таблице 34.
5.2. Все функции ПС05 должны ...
5.3. В режиме ... функции ПС05 должны ...
Таблица 34. Состав функций ПС05 и требования к ним
ТАБЛИЦА


Такой вариант оформления позволяет вставлять любое число абзацев до и после таблицы.

V. Рисунки

1. Используется слово «рисунок»


Хотя я и сам часто его и использую.
Рисунок не обязывает к точной передаче данных.
Более правильное использование слов «диаграмма» и «схема» сразу ставит вопрос о формате, нотации или соглашении «как читать диаграммы».
Если применяется стандартная нотация, можно при ссылке из текста или в названии так и написать диаграмма <ЧЕГО>. Например, диаграмма вариантов использования (UML) или диаграмма потоков данных (в нотации Йордона/ Де Марко). Если в документе вы определяете свой формат, вы можете коротко описать его при упоминании или сослаться на соглашение «как читать диаграммы», приложенное к документу.

2. Рисунки не пронумерованы


Полностью повторяет такую же проблему для таблиц. п.IV.8.

VI. Формулировки

1. Разные названия для одного и того же объекта


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

2. Распространение контекста за пределы абзаца


Контекст должен сбрасываться с каждым новым абзацем. Если предстоит много правок с разных сторон (например, как при согласовании договора), то лучше вообще с каждым новым предложением. Так как любая правка может оборвать стройное течение мысли.
Хороший прием для проверки контекста – вычитка документа задом наперед с последних абзацев к первым.


Пример.
Было:
1. Узел Системы У1 предназначен для размещения базы данных Системы и компонентов РСУБД.
2. Он должен размещаться на территории Заказчика.


Стало:
1. Узел Системы У1 предназначен для размещения базы данных Системы, компонентов РСУБД и сервера приложений.
2. Заказчик обеспечивает следующие параметры канала связи между У1 и сетью Интернет:
а) Средняя скорость отдачи данных от У1 в Интернет не менее ...
б) Средняя скорость получения данных на У1 из Интернет не менее ...
в) Время отклика ...
3. Он должен размещаться на территории Заказчика.


Еще пара вставок и концы не найдутся.


Как правильно:
1. Узел Системы У1 предназначен для размещения базы данных Системы и компонентов РСУБД.
2. Узел Системы У1 должен размещаться на территории Заказчика.
При любом перемешивании пунктов смысл не меняется.

VII. Еще ряд советов

1. Внятные подписи комментариев


При использовании рецензий MS Word надо обеспечить, чтобы подписи комментаторов легко различались. То есть подпись «office12: предлагаю убрать» сложнее понять, чем «Иванов А.П.: предлагаю убрать».
Если согласование идет в узкой группе, можно использовать ники. Если согласующих много, вообще лучше переходить к использованию сводки замечаний.

2. Используйте шаблоны


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


Задачи по дополнению



 
Файлов нет.[Показать файлы/форму]
Комментариев нет. [Показать комментарии/форму]