• Как правильно вести техническую документацию Системному администратору?

    @Madguy
    System Engineer, student in MTUCI
    Присоединяюсь ко всем, кто высказывает я в пользу наличия аккуратно документации. Ниже приведу принципы, которыми успешно пользуюсь сам. Надеюсь, они помогут вам сформировать свое мнение и встать на "светлую сторону" силы.

    Сначала скажу о плюсах документации:
    - она помогает вам учиться грамоно структурировать информацию
    - есть хорошая вероятность, что в будущем вы сами сможете ею воспользоваться и скажете себе "спасибо" (проверено)
    - ею сможет воспользоваться ваш преемник или коллега/руководитель. И, если от преемника вы маловероятно получите какую-либо выгоду кроме морального удовлетворения, то ваш во 2-ом случае это сыграет вам на пользу. Вам будет проще объяснить своему коллеге (да и руководителю) принцип работы, чтобы втянуть его в работу. Руководитель сможет увидеть один из результатов вашей работы, и вы станете более ценным сотрудником в его глазах.
    Тут ещё куча плюсов может нарисоваться, но это самые главные.

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

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

    На этом пока все. Есть ещё куча подходов и принципов, а также много литературы и где-то завалялся недавний выпуск подкаста. Если будет интересно - скину, а то с планшета неудобно
    Ответ написан
    1 комментарий