Любой фрагмент информации, над получением которого пришлось думать (например, гуглить), стоит документировать. Иначе над ним придется думать еще раз, и, возможно, в более неудачных обстоятельствах.
Возможна документация, какая получится, или никакая. Первое лучше.
Внутренняя документация - это живое растение, что-то в ней устаревает, что-то дописывается. Добиться его упорядоченности невозможно, достаточно, чтобы им было можно пользоваться.
Внутренняя документация должна быть в одном месте, потому что только одном месте ее будут искать.
К внутренней документации следует предъявлять минимум формальных требований. Иначе ее не будет.
Копипаста из рабочего чата и цитаты из history, c какими-то комментариями - это уже неплохо.
А вот контекст - к какой версии софта, ОС, и исторической эпохе относится нижеописанное, лучше обозначить явно и в начале текста. Потому что сейчас это очевидно, а через 5 лет, когда эта информация понадобится, станет загадочно.
Документировать никто не любит, поэтому документировать должно быть просто. Что значит “просто”, зависит от конкретных людей. В маленькой фирме, где все - IT-шники, использовать несложный язык разметки вместо WYSIWYG - эт нормально. В других местах это может быть по-другому. Но порог “вхождения в документирование” должен быть максимально низким, или документации просто не будет.
Имхо, наилучший момент для документирования - “когда нечто воспроизводимо получилось”. Раньше - в документацию может попасть лажа. Позже - знание будет вытеснено из головы другими задачами.
Под документирование должно быть выделено время. Лучше всего - пока информация свежа. Мне нравится считать документирование последней стадией решения задачи.
Другое время для приведения внутренней документации в порядок не будет выделено никогда, поэтому все сразу должно быть достаточно сносно.
Невозможно создать такую структуру внутренней документации, которая бы самоподдерживалась и была бы полезна в течении долгого времени. Какие-то разделы разрастаются, и в них ничего не найдешь, какие-то хиреют, но упорно занимают место в иерархии. Хотя полнотекстовый поиск - это хорошо, имхо, наиболее адекватна будет расстановка тегов. В качестве тегов стоит использовать и те слова, которыми контексты называют
Внешние ссылки с хорошими описаниями - это полезно. Но через 5 лет они могут просто исчезнуть. Поэтому все важное оттуда надо копипастить.
Иногда лучшей документацией к тому, что надо сделать, оказывается скрипт, который это делает.
Имхо, появления фрагмента документации в хранилище документации недостаточно. Нужен какой-то анонс, в мыл или корпоративный чат, чтобы заинтересованные лица сумели заметить “у нас где-то это было”
Пожалуй, для внутреннего документирования наиболее полезны удобный инструмент и хорошая традиция, а не регламент
Дополнения и осмысленные комментарии приветствуются.
UPD - иногда документацию имеет смысл простестировать - скормить коллеге, чтобы он сделал все по инструкции и обругал все, что не понял
