nasse (nasse) wrote,
nasse
nasse

Categories:

Сага про внутреннюю документацию

Попытка сформулировать нечто о внутреннем документировании.

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


Возможна документация, какая получится, или никакая. Первое лучше.

Внутренняя документация - это живое растение, что-то в ней устаревает, что-то дописывается. Добиться его упорядоченности невозможно, достаточно, чтобы им было можно пользоваться.

Внутренняя документация должна быть в одном месте, потому что только одном месте ее будут искать.

К внутренней документации следует предъявлять минимум формальных требований. Иначе ее не будет.
Копипаста из рабочего чата и цитаты из history, c какими-то комментариями - это уже неплохо.
А вот контекст - к какой версии софта, ОС, и исторической эпохе относится нижеописанное, лучше обозначить явно и в начале текста. Потому что сейчас это очевидно, а через 5 лет, когда эта информация понадобится, станет загадочно.

Документировать никто не любит, поэтому документировать должно быть просто. Что значит “просто”, зависит от конкретных людей. В маленькой фирме, где все - IT-шники, использовать несложный язык разметки вместо WYSIWYG - эт нормально. В других местах это может быть по-другому. Но порог “вхождения в документирование” должен быть максимально низким, или документации просто не будет.

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

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

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

Невозможно создать такую структуру внутренней документации, которая бы самоподдерживалась и была бы полезна в течении долгого времени. Какие-то разделы разрастаются, и в них ничего не найдешь, какие-то хиреют, но упорно занимают место в иерархии. Хотя полнотекстовый поиск - это хорошо, имхо, наиболее адекватна будет расстановка тегов. В качестве тегов стоит использовать и те слова, которыми контексты называют в курилке у кофеварки. Так их хотя бы найдут.

Внешние ссылки с хорошими описаниями - это полезно. Но через 5 лет они могут просто исчезнуть. Поэтому все важное оттуда надо копипастить.

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

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

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

Дополнения и осмысленные комментарии приветствуются.

UPD - иногда документацию имеет смысл простестировать - скормить коллеге, чтобы он сделал все по инструкции и обругал все, что не понял
Tags: Компьютерное
Subscribe

  • (no subject)

    Пипл, дурацкий вопрос. Какие максимальные аптаймы у вас получались на одноплатниках, и на каких конкретно одноплатниках?

  • (no subject)

    К предыдущему, про визуальный ряд к безозопасности данных. Из Сказки о царе Салтане , https://ilibrary.ru/text/455/p.1/index.html , И царица над…

  • (no subject)

    Вдруг кто-нибудь в ИИ разбирается? Почти теоретический вопрос. Есть последовательности таймстампов, отмечающие, когда юзер заходил на некоторый…

  • Post a new comment

    Error

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 39 comments

  • (no subject)

    Пипл, дурацкий вопрос. Какие максимальные аптаймы у вас получались на одноплатниках, и на каких конкретно одноплатниках?

  • (no subject)

    К предыдущему, про визуальный ряд к безозопасности данных. Из Сказки о царе Салтане , https://ilibrary.ru/text/455/p.1/index.html , И царица над…

  • (no subject)

    Вдруг кто-нибудь в ИИ разбирается? Почти теоретический вопрос. Есть последовательности таймстампов, отмечающие, когда юзер заходил на некоторый…