Документация, которую действительно читают
Её не пишут не из лени, а потому что непонятно, для кого. Пишешь долго, а читателя не видно.
Смените цель: не «описание системы», а ответы на вопросы, которые уже задавали. Спросил новичок, как запустить проект, — записали. Второй раз объясняете, почему тут два похожих справочника, — записали. Через полгода получится документ, состоящий только из нужного.
Правила, чтобы он не сгнил. Держать рядом с кодом, а не в отдельном месте, куда никто не заходит: документ, который врёт, хуже отсутствующего. Ставить дату и автора. Писать короче, чем хочется: страница, которую дочитывают, полезнее двадцати, которые открывают и закрывают.
Что записывать в первую очередь: как запустить, как выкатить, что делать при типичных сбоях, кто за что отвечает и почему приняли ключевые решения. Последний пункт спасает от бесконечного возвращения к спорам, которые уже закрывали.
И побочный эффект: человек, к которому приходят за знаниями, потому что он их однажды записал, получает влияние без всякой должности.
IT Владимир — t.me/itnews_vladimir
IT Владимир
@itnews_vladimir
Документация, которую действительно читают
Этот пост опубликован в Telegram-канале IT Владимир. Подписаться можно по ссылке: @itnews_vladimir.