Меня зовут Семён Факторович, с 2012 года я занимаюсь технической документацией. Последние три года я руковожу собственным агентством documentat.io, помогая российским IT-компаниям создавать качественную документацию.

Мы пишем документацию с нуля (руководства пользователя, справочники API, архитектурную документацию) и поддерживаем уже имеющуюся и проводим консультации по настройке документационных процессов. И почти каждый запрос от наших клиентов начинается с признания: «Кажется, с нашей документацией что-то не так».

Когда мы начинаем углубляться, разбираясь, что с ней не так, то очень часто причины довольно одинаковы и повторяются от компании к компании. Если свести их в один список и отсортировать по частоте озвучивания, то получится такой хит-парад проблем:

1) Документация полностью отсутствует.
2) Документацию неохотно пишут.
3) Документацию неохотно читают.
4) Документация есть, ее пишут и читают, но она кажется бесполезной.

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

Эти проблемы я и хочу сегодня обсудить: посмотрим их симптомы и как их интерпретировать, а самое главное — что с ними делать. Предлагаю вам некую методичку по самодиагностике и самолечению проблем с вашей документацией. Всё, приведенное ниже, опробовано на нескольких десятках IT-компаний.

• Хабр: Как технологии манипулируют вашим разумом: взгляд иллюзиониста и эксперта по этике дизайна Google (альтернативная версия)
• TED: Как усовершенствованные технологии помогут нам сосредоточиться

Один крест (+) означал, что посыльный мог ехать к месту назначения шагом, два креста (++) означало рысь, три креста (+++) — незамедлительный галоп. Поэтому в армии галоп носил неофициальное название аллюр три креста, а позже это выражение вошло в русский язык, имея смыслом максимально быстрое выполнение поручения начальства. [Википедия]

Tar pit (англ., дословно смоляная яма) — 1) неразрешимая проблема, 2) битумное озеро (место, где подземный битум выходит на поверхность, создавая участок природного асфальта). [Англо-русский словарь] Животные, попавшие в битум, не могут выбраться обратно, поэтому такие озера являются отличным местом для раскопок доисторических скелетов [Википедия].

«Воображение представляет динозавров, мамонтов и саблезубых тигров, пытающихся высвободиться из смолы. Как бы ни был силен или ловок зверь, в конечном итоге ему уготована гибель. Такой смоляной ямой в последнее десятилетие было программирование больших систем...» [1, с.16] С этого яркого образа начинается классическая книга Фредерика Брукса, впервые увидевшая свет в далеком 1975 году. Другая классическая книга, опубликованная в столь же древнем 1987-м, начинается ничуть не лучше: «А в это время где-то гибнет проект» [2, с.23]. Идут годы, человечество вступает в новое тысячелетие, но и в 2014 году очередной бестселлер начинается все с той же вечной истории: «3 марта 2010 года Федеральное бюро расследований решило приостановить свой крупномасштабный и многообещающий план модернизации управления информацией… В бюро пытались обновить свою компьютерную систему уже более десяти лет, и, похоже, их постигла катастрофа» [3, с.14].