Комментарии 21
Радует систематизация в статье! Подскажите, как вы видите процесс по отладке документации под критерии качества?
Спасибо. А кто устанавливает эти критерии и в чем они заключаются? Это внутренняя потребность или внешняя? Что есть состояние А и Б?
Для начала нужно посмотреть на процесс производства:
Кто и как его контролирует, по какой методологии?
Где и как фиксируется постановка задач по проектам?
Какова политика компании по документированию?
К основным критериям качества я бы отнес:
1. Внешний вид – всё, что связано с визуальной подачей текста. Здесь нужны рекомендации по оформлению и контроль за их исполнением. Документ не должен уходить "в прод" без проверки – это также позволит выявить явные ошибки и сохранить лицо фирмы.
2. Актуальность описаний - про политику документирования.
- Кто и как составляет эти описания? Кто ведет мониторинг за внешними ресурсами?
Примеры:
- Эксперт написал статью и она не обновляется, потому что про нее никто не знает;
- Вышел новый протокол и заказчик спрашивает про сроки, а компания не в курсе;
- Нужно ли усиливать команду или это вопрос к SLA и Каталогу услуг?
- Можно ли изменить основной процесс или статусную модель ведения задач?
3. Полноту сведений – что должно быть и что должно отсутствовать.
- Как построено согласование с экспертами?
Пример:
Аналитик написал ТЗ на новый модуль. Тестирование прошло успешно и разработка описана. Но никто не учел, что описание старого модуля нужно исключить. Или наоборот, оставить, но с припиской "для совместимости".
- Проводятся ли мероприятия по ретроспективе, в том числе и с заказчиком?
- Фиксируется ли опыт заказчика на этапах внедрения и эксплуатации?
---
Иными словами, это всё про регламенты и процессы. Но избыточный контроль повышает нагрузку на руководителя и вызывает стресс у сотрудника. Поэтому не менее важна корпоративная культура – когда все знают что и зачем они делают.
UPD. Обновлены примеры критериев и добавлены сноски в примечаниях. Надеюсь, администраторы Хабра не забракуют статью из-за таких незначительных правок.
Толковая систематизация. Привнесу немного критики чистого разума.
Совсем не упомянута структура представления информации в том смысле, в каком это слово употребляется в словосочетании «структура данных». При этом упомянуты ГОСТ 19 и 34, но — в разделе про тиражируемость, тогда как эти стандарты регламентируют как раз не вопросы тиражируемости, а вопросы структуры данных. Надо признать, не лучшим образом они это регламентируют, но это другой вопрос.
Мне видится разумным делить все сведения в документации по-американски: на решение задач, справку, и концептуальные описания. Если требуется соблюдать ГОСТ, соблюдаем ГОСТ.Вес критериев стоимости неодинаков. Стоимость изготовления документации хорошо бы всячески уменьшать, но экономить на документации плохо. А вот стоимость чтения материалов надо уменьшать всеми силами, чтобы спросить у коллеги всегда было дороже. Иначе однажды коллега уволится, и тогда выбора не будет.
Критерии оценки тиражируемости не имеют отношения к тиражируемости. Возможности экспорта в другие форматы тоже не определяют тиражируемость. Даже набранный на машинке текст полувековой давности уверенно распознаётся компьютером, после чего неограниченно тиражируется. А уж электронные форматы и подавно конвертируются из любого в любой, ну кроме каких-то совсем экзотических случаев.
Критерии оценки тиражируемости в этой статье на самом деле — критерии оценки пригодности формата к конкретным условиям производства документации. Условный ворд есть у всех, но групповая работа, слияние правок и управление версиями часто и легко превращаются в квадратуру круга. Вики и маркдаун решают проблему управления версиями, но требуют средства конверсии в другие форматы.
Спасибо, эта статья не идеальна. Под "тиражируемостью" я подразумеваю "переносимость" содержимого между разными форматами и системами. Очевидно, что как бы хорош не был текст в Ворде, это автоматически не означает, что он будет соответствовать какому-либо ГОСТу.
Согласитесь, переносимость и тиражируемость — прилично разные вещи. Я всё ещё уверен, что в принципе проблемы переносимости не существует: сейчас есть и распознавание текста, и авторедактирование нейросетями, и регулярные выражения для мелких технических работ. Не буду повторяться, вы и без меня это всё знаете. :)
На самом деле у вас пункт 9 "Тиражируемость" подсвечивает объёмный пласт сложностей и решений, которые нужно принять заранее, перед производством. Очень хорошо, что вы обратили внимание публики на это, потому что во многом именно решения, принятые при ответах на поставленные в пункте вопросы, определяют стоимость и сложность поддержки документации, да и продукта в целом.
По поводу ГОСТов добавлю: ГОСТы не про то, что в документе будет титульный лист, отступы 1,25 см, и шрифт Таймс Нью Роман. Это всё ерунда. На самом деле ГОСТы — про то, что будет написано, в какой последовательности, и иногда какими словами. Именно в этом их польза, и именно это отличает документацию по ГОСТ от документации, написанной как-то иначе.
Ну и ещё немного критики чистого разума по мелочи, зато с цитатами.
Макет страницы и типографика[5];
Ссылки на яндекс — воля автора, но вот некликаемые неинтерактивные ссылки на источники в вебе — это смело. :) Если ближе к делу: в случае с гибкими электронными документами (HTML, Wiki, и т.п.) хорошо бы следить за максимальной длиной строк, которая не должна превышать примерно 50 (в крайнем случае 80) знаков, иначе её будет неудобно читать. Да, сюда же размер шрифта на экране: по неясной причине его все экономят, тогда как экономить лучше зрение читателя.
Грамотность — оценка материала за правописание и речевое оформление
Полностью согласен, но прикольно, что среди списков, построенных на простом перечислении или вопросах, конкретно этот построен на имплицитно отрицательных примерах. Полагаю, что если уж давать чеклист, то правильные ответы в нём каждый раз должны быть сводимы к слову «ДА», а не «НЕТ».
Местоимения типа «вы», «вам», «вас» с большой буквы;
В советские времена в технической документации было принято вообще никак не обращаться к читателю, а описывать его действия во множественном числе третьего лица: «Числительные от 1 до 10 приводят словесно, начиная с 11 числительные дают цифрами». На мой взгляд, неплохой стиль, но привычки к такой речи обычно нет, поэтому формулировать трудно.
Полнота — описания определяется опытным путем
От себя добавлю: в отношении полноты обязательно стоит руководствоваться принципом «только свой контент». Например, если используют чужой компонент в составе своего продукта или изделия, документировать у себя нужно только то, что нельзя прочитать в документации этого компонента. Например, взяли какой-то блок, настроили под себя, и описали только то, что настроили. Тогда не придётся поддерживать актуальность чужой документации.
Могут понадобиться изменения в процессах производства или корпоративной культуре
Тут техпис скорее в слабой позиции. Прибыль компании обычно генерируют другие люди, а техпис скорее как бухгалтер или сисадмин: их присутствие убыточно, но их отсутствие зачастую обходится сильно дороже. Я одно время работал в компании, где техписы вообще ни у кого ничего не спрашивали, а сами рыли информацию везде где можно. Я, например, описание какого-то технического решения нашёл на скане бумажки, нарисованной по итогам совещания, и заброшенной в Конфлюэнс полтора года назад. Напротив, обычно инженеры сами пишут, что они сделали, а потом техпис приводит написанное инженерами в документ, приемлемый для чтения людьми.
Одного ли размера скриншоты и не сливаются ли с текстом
А ещё — читаемы ли скриншоты при штатном отображении документации? Например, различимы ли на экране или при печати.
Хорошие дополнения.
Про ссылки в квадратных скобках? Изначально писал в маркдауне и тогда мне казалось, что ссылки будут сливаться. Вообще я против всяких сносок и примечаний, но не придумал решения лучше. Скорее недоработка, никакой смелости :)
Про грамотность. Здесь я исходил из веры в то, что пользоваться Вордом и уметь расставлять запятые подвигом уже не назвать. Статьи бывают разными, но обращение на "Вы" меня огорчает.
Полагаю, что "слабую позицию техписа" должна исправить позиция Менеджера по знаниям, которая на рынке почти не представлена.
Про различимость скриншотов актуально! Хотя это больше к Ворду относится. Я бы не стал рассматривать печатные варианты, это странно. Видимо, наличие Базы знаний это тоже вопрос про уровень зрелости компании. Где-то на просторах Хабра читал комментарии, дескать и Конфлюенс базой знаний не является, но я не готов об этом дискутировать.
я исходил из веры в то, что пользоваться Вордом и уметь расставлять запятые подвигом уже не назвать.
Тем не менее, по моим прикидкам пользоваться вордом умеют не все даже среди тех, кто пользуется им ежедневно. Я на работе каждый день встречаю то отступы, отбитые пробелами, то оформление поверх стилей, то нумерацию вручную, то ещё бог весть что. Картинки и те все по-разному вставляют. Другое дело, что и сам Ворд изрядно способствует тому, чтобы им пользовались нерационально.
Статьи бывают разными, но обращение на "Вы" меня огорчает.
Меня тоже. Это окей в официальном стиле документов вроде ответов на обращение гражданина в префектуру, но в документации вряд ли уместно. Я обычно использовал такой аргумент: на "Вы" обращаются лично к конкретному читателю, а на "вы" — неопределённому кругу читателей.
"слабую позицию техписа" должна исправить позиция Менеджера по знаниям, которая на рынке почти не представлена.
По мне это говорит о том, что менеджеры по знаниям не нужны бизнесу. Ему, собственно, и техписы не нужны сами по себе, они практически не создают прибавочную стоимость. Ну очень условно её создают, примерно как дизайнеры упаковки.
Я бы не стал рассматривать печатные варианты, это странно.
Ну как странно. Я вот купил смарт-часы — в коробке лежит вполне себе печатное руководство по эксплуатации. Купил автомобиль — там целая книга. Собственно, вопрос печатной документации это вопрос условий эксплуатации продукта. Я уж не говорю про всякую экзотику вроде взаимодействия с военными, или как у меня, в электронике, с соисполнителями и заказчиками. Там наоборот электронная документация чаще всего не предназначена для чтения людьми, а та, что предназначена, исполняется в пригодном для печати виде, хочу я этого или нет. :))))
Неразличимые скриншоты запросто встречаются и в электронном виде. Типичный пример — кликабельный скриншот интерфейса, уменьшенный вчетверо от оригинала, для экономии места на экране. Или наоборот — гигантский скриншот размером 4К, на котором полезная информация дана по краям, и надо скроллить горизонтально.
Сведу все в один коммент.
Согласитесь, переносимость и тиражируемость — прилично разные вещи
Соглашусь, поменял. Заодно обновил сноски, но не помогло.
ГОСТы — про то, что будет написано, в какой последовательности, и иногда какими словами
Вот это последнее меня и смущает. Если поменять структуру еще как-то можно, то, скажем, с адептом "Пиши, сокращай" предвижу сложности.
Пользоваться вордом умеют не все даже среди тех, кто пользуется им ежедневно
Форматирование в Ворде занимает лютую долю времени, я не понимаю выгоды таких мучений.
Менеджеры по знаниям не нужны бизнесу
Да, если функционала техписа и методолога вполне достаточно.
Если на Западе таких вакансий много, то либо они что-то знают, либо тут какой-то подвох. Кажется, компании еще не созрели и не понимают что с этим делать.
Я встречал 2 сценария:"Нам нужен человек, который будет убеждать все отделы вести 1 базу знаний" (вопрос о весе инициатора идеи в компании остался без ответа);
"Нам нужен человек, который переведет все вордовские документы в базу и будет ее курировать" (есть риск, что на этом все и закончится);
Есть категория людей, которая про "знаю, но ничего не расскажу, иначе потеряю свою ценность". И есть компании, которые формируют такую корпоративную культуру.
Я вот купил смарт-часы — в коробке лежит вполне себе печатное руководство по эксплуатации
А я вот купил автомобиль, а в инструкции нет описания индикаторов бортовой панели. А я вот купил наушники от Apple, но не понял как работают нажатия. А я вот купил роутер, а там вообще нет никакой инструкции, даже QR-кода со ссылкой на сайт.
У меня нет однозначного мнения. С одной стороны, мне нравятся печатные издания (магия законченности, убитая эджайлом), а с другой, это кажется компромиссом между "напечатать как можно меньше" и "чтобы было понятно".
обновил сноски, но не помогло.
В Хабраредакторе была фича с всплывающими подсказками по клику вроде бы. Не помню, какой тег, но фича была. Никоим образом не советую, просто для информации. На мой вкус, примечания в конце страницы ещё объяснимы в книге, но скроллить несколько экранов — гарантированно разорвать контекст, особенно у людей, непривычных к длинным текстам.
Если поменять структуру еще как-то можно, то, скажем, с адептом "Пиши, сокращай" предвижу сложности.
ГОСТы не прибивают структуру гвоздями, а скорее напоминают, о чём ещё надо не забыть написать. А часто — ещё и какими вопросами озадачиться. С адептом "Пиши, сокращай" я сложностей не предвижу: технический язык располагает к лаконичности, и притом находится вне области определения "Пиши, сокращай". Стандартные заклинания вроде "Настоящие технические условия (ТУ) распространяются на..." — имеют скорее юридический смысл и происхождение примерно оттуда же. Можно не писать это, по закону использовать ГОСТ не обязательно. Заказчик может возразить, но это проблема другого рода.
Форматирование в Ворде занимает лютую долю времени, я не понимаю выгоды таких мучений.
Я лично не сторонник употребления ворда и т.п., но иногда продавить иные решения не представляется возможным. Текстовые языки разметки в этом отношении не проще: их как минимум надо знать. Я не питаю иллюзий о том, сколько инженеров у меня в отделе готовы перейти на маркдаун или что-то ещё.
Я немного грокнул секрет избавления от возни, вернее, я его знал из смежной профессии: надо один раз нарулить стили, записать их в стандартный шаблон normal.dot, и раздать всем причастным. Это где-то день или два работы, зато потом текстовый процессор можно использовать чисто для набора, а оформление произойдёт само по себе. Это имеет смысл всякий раз, когда приходится работать в ворде.
Менеджеры по знаниям не нужны бизнесу
Да, если функционала техписа и методолога вполне достаточно.
Вообще это тянет на большую дискуссию или даже на статью, поэтому я просто соглашусь. В рамках моего опыта так и есть, хотя я много чего могу не знать.
Нам нужен человек, который будет убеждать все отделы вести 1 базу знаний" (вопрос о весе инициатора идеи в компании остался без ответа)
По-моему, у нас это чаще всего решается на уровне того или иного руководителя проекта. Не готов исключить, что в мегаструктурах вроде Сбера есть какие-нибудь менеджеры по знаниям. Когда я заступал на работу, там обычно уже были какие-то базы знаний, видимо, самозародившиеся вместе с фирмой. В других организациях таких баз не было, и тогда даже не просматривалось возможности их внедрить. На текущей работе как раз такая ситуация.
"Нам нужен человек, который переведет все вордовские документы в базу и будет ее курировать" (есть риск, что на этом все и закончится);
Тут довольно большой вопрос, что значит курировать. Особенно если есть сотрудники, настроенные против такой базы.
Есть категория людей, которая про "знаю, но ничего не расскажу, иначе потеряю свою ценность". И есть компании, которые формируют такую корпоративную культуру.
Да, это так. Я как раз сейчас наблюдаю похожую ситуацию. Есть сотрудники, которые что-то знают, и всем плевать, что заменить их некем, потому что они пока никуда не уходят. Недавно была ситуация: уволился начальник отдела и одновременно ведущий специалист по проекту, оставив после себя чистый компьютер. На мой вопрос, кто будет доделывать его работу, новый начальник отдела ответил коротко: "Никто". Как при таких обстоятельствах закрывали проект — отдельная история не для комментариев в открытой печати.
С одной стороны, мне нравятся печатные издания (магия законченности, убитая эджайлом), а с другой, это кажется компромиссом между "напечатать как можно меньше" и "чтобы было понятно".
А я где-то выше уже говорил: всё зависит от условий эксплуатации документируемого продукта и документации. Если я что-то программирую в Матлабе, нафиг мне не надо книгу, мне хватит интерактивной документации. А если у меня микросхема или радиостанция, документация в печатаемом формате уже будет полезна.
Наверное тут можно дискутировать бесконечно.
Знаешь, у меня есть 1 непопулярная мысль, что людей везде учат что-то делать, но никак не описывать то, что они делают. Как будто те, кто в школе хорошо справлялся с сочинениями, пошел в пиар (рекламу, копирайтинг и т.п.). Остальным - "ну, у нас как-то так". А вот еще статью нашел (надеюсь, это не запрещено).
...людей везде учат что-то делать, но никак не описывать то, что они делают.
Я в первом вузе много раз слышал от одного из преподавателей фразу "Кто ясно мыслит, ясно излагает", каковой он всем студентам с бессвязной речью намекал на бессвязность мыслей в их голове. :) Написать понятно для себя могут многие, а понятно для других — этому надо учиться специально.
Со сказанным по ссылке в целом согласен, но с оговорками, и ещё поправкой на то, что мы редко утруждаем себя чтением иноязычной литературы, которая не заходит сразу, а это порождает смещение выборки.
В Хабраредакторе была фича с всплывающими подсказками по клику вроде бы.
Нашел, воспользовался. Хотя тут палка о двух концах. Как статья - выглядит чище и контекст не разрывает, но как поиск не работает.
Про печатный формат - кажется, это отдельный вид искусства, т.к. это не столько вопрос верстки, сколько написать так, чтобы обойтись без гиперссылок. Вот бы гайд на какой-нибудь Микротик с несколькими сценариями настроек получить! Кстати о вендорах. Понятно, что они продают обучение и поддержку своей продукции, но я заметил 2 подхода:
"Ну вот мы вам рассказали курс, вы записали что смогли, далее экзамен и в добрый путь". Через энное время я это забуду, а мои записи потеряют практический смысл.
"Вот вам краткий конспект тезисов - делайте заметки". Через энное время у меня будет внятная информация по предметной области.
печатный формат - кажется, это отдельный вид искусства, т.к. это не столько вопрос верстки, сколько написать так, чтобы обойтись без гиперссылок.
В печатном (или пригодном для печати) формате приходится задумываться о том, с чем в электронном формате можно вообще никогда не столкнуться. Надо помнить о маркировке документа, о порядке и способах его обновления, о навигации (гиперссылок-то нет), о производстве и хранении документа, иногда ещё об условиях его эксплуатации (например, о необходимости читать в потёмках). Иногда приходится изворачиваться с вёрсткой длинных таблиц (например, не забыть прибить заголовок таблицы на каждой странице), о висячих строках и заголовках, ну и о прочем подобном. Но эти проблемы видно, и они несложные.
Гиперссылки в печатном документе не проблема. Их заменяют ссылки на страницы, и сноски. Отчасти помогают алфавитный указатель и глоссарий.
"Ну вот мы вам рассказали курс, вы записали что смогли, далее экзамен и в добрый путь". Через энное время я это забуду, а мои записи потеряют практический смысл.
В этом месте рекомендую брошюру "Скоростное конспектирование", которая меня выручает с десятого класса школы. Правда, неиспользуемое знание всё равно будет забыто даже с очень хорошим конспектом.
"Вот вам краткий конспект тезисов - делайте заметки". Через энное время у меня будет внятная информация по предметной области.
Чем это отличается от случая выше, я не понял, потому что чужие конспекты читаю так же плохо, как забытые свои. :) По-моему, чем больше документации на руках, чем лучше она написана, и чем чаще мы пользуемся ею или продуктом, тем лучше мы знаем продукт. Вроде так.
Здесь не про скорость конспектирования, а про донесение информации. Второй случай существенно экономит ресурсы на восприятие. Или писать, или слушать. Предвижу возражение. Да, когда пишешь от руки, то предмет усваивается лучше, но увы - это касается онлайн-курсов, когда можно несколько раз пересмотреть и записать то, что нужно. Никогда не понимал преподавателей, которые всю пару выводили какую-то формулу на доске.
Тут, мне кажется, всё проще: когда учебных материалов дают меньше необходимого, возникают все вот эти проблемы утраты информации. Хороший вариант по современным временам — медиазапись лекции с разметкой по времени, и подробный авторский конспект, а если лекций много, то ещё к этому учебное пособие. Лекцию, проведённую даже как-нибудь, можно пересматривать до талого и однажды всё-таки понять. Конспект можно испытать и отполировать до совершенства. Учебное пособие — в конце концов, они бывают готовые.
Важна методика. Даже в вузах хорошие методисты встречаются хорошо если через одного (а по-моему и много реже), а в народном хозяйстве хороших методистов и вовсе днём с огнём, хотя иногда встречаются.
материалов дают меньше необходимого
Кто знает сколько их необходимо? Как научить человека учиться? С другой стороны - если человеку дать все готовое, сможет ли он это принять? Имеет ли смысл привлекать студентов к написанию/корректировке методических материалов (Хороший вариант по современным временам — медиазапись лекции с разметкой по времени)? Имеет ли смысл институтам задуматься о переосмыслении хранения знаний по своему профилю?
Лекцию, проведённую даже как-нибудь, можно пересматривать до талого и однажды всё-таки понять.
В этом ключевая проблема всех ВУЗов (я знаю, что "вуз" пишется так, но не согласен с этим) - нет времени мусолить 1 и ту же лекцию, которая, к тому же, зависит от массы иных материалов. И так до бесконечности.
Критерии оценки документации