Присоединяюсь ко всем, кто высказывает я в пользу наличия аккуратно документации. Ниже приведу принципы, которыми успешно пользуюсь сам. Надеюсь, они помогут вам сформировать свое мнение и встать на "светлую сторону" силы.
Сначала скажу о плюсах документации:
- она помогает вам учиться грамоно структурировать информацию
- есть хорошая вероятность, что в будущем вы сами сможете ею воспользоваться и скажете себе "спасибо" (проверено)
- ею сможет воспользоваться ваш преемник или коллега/руководитель. И, если от преемника вы маловероятно получите какую-либо выгоду кроме морального удовлетворения, то ваш во 2-ом случае это сыграет вам на пользу. Вам будет проще объяснить своему коллеге (да и руководителю) принцип работы, чтобы втянуть его в работу. Руководитель сможет увидеть один из результатов вашей работы, и вы станете более ценным сотрудником в его глазах.
Тут ещё куча плюсов может нарисоваться, но это самые главные.
Принципы:
- пишите документацию так, чтобы человек с минимальными знаниями по теме мог разобраться о чем идёт речь
- в большинстве статей вы скорее всего будете описывать решение конкретной задачи
- остальные статьи, верятно, будут иметь описател ный характер (схема сети, расмещение серверов, список доменов, список можете продолжить сами)
- описывайте только главное, не углубляйтесь в подробности и основы. Для этого есть официальная документация. Вместо описывания основ, дайте ссылку на документацию и пометьте какую информацию там можно найти.
- ведите структурированную документацию там, где возможно. Введите минимал ные разделы: "описание", "ссылки", "инструкция". "Описание" - здесь пишите какую проблему решаете и что получаете на выходе. "Ссылки" - собираете тут все ссылки, которые указали в статье. "Инструкция" - тут непосредственно сами шаги, которые привели вас к нужному результату. Также в начале этого раздела можно привести список требований (наличие root/админского доступа, наличие нестандартных настроек приложенияя/веб-сервера/системных настроек и тд).
- в описании или в начале инструкции дайте пару основных определений, которыми будете оперировать в статье.
- не стесняйтесь приводить иностранную документацию и ссылки, а также не забывайте сами её читать. Сегодня есть отличные инструменты для этого, даже если вы не знаете другой язык. Встроенный переводчик в Google Chrome может перевести сразу всю страницу. Расширение для Google Chrome - LinguaLeo может перевести конкретное слово (пр двойном нажатии на слово)
Хорошая документация не обязательно требует наличия красивых схем и скриншотов. В большинстве случаев достаточно аккуратного описания. Но в некоторых случаях могут понадобится схемы. Тут можно использовать как скриншоты, так и сделать схему самому. Очень гибкий бесплатный веб инструмент для разных схем - draw.io
На этом пока все. Есть ещё куча подходов и принципов, а также много литературы и где-то завалялся недавний выпуск подкаста. Если будет интересно - скину, а то с планшета неудобно
