Со временем я занимался консультированием и подрядным проектированием для различных клиентов. В последнее время клиенты запрашивают определенные типы документации.
Это малые предприятия, которые обычно не имеют специального технического персонала. В рамках одной компании Wiki / Confluence / Sharepoint и т. Д. Имеют смысл в качестве центрального хранилища документации и информации о среде, но мне трудно найти последовательный метод для доставки этой информации дискретный клиентов.
Я стремлюсь к процессу, который будет более портативным, безопасным и элегантным, чем простая электронная таблица или ужасный папка с устаревшей информацией.
Я знаю, что здесь есть и другие консультанты. Есть ли какие-либо предложения или советы по ведению документации в различных средах в удобном для пользователя формате? Как делать ты сделай это?
С июня 2004 года я являюсь партнером в контрактной / консультационной службе из трех человек. Каждый из нас в основном работает со своими «учетными записями», однако нам необходимо вести документацию друг для друга, чтобы обеспечить «переключение» между партнерами. У большинства наших клиентов есть внутренний ИТ-персонал, многие из которых выполняют определенное количество повседневных работ по обслуживанию, и нам также необходимо эффективно передавать им документацию.
У двух моих партнеров есть преимущество (если это можно так назвать) в том, что они работали под моим руководством в другой фирме, и в результате они оба были приучены к моему самоуверенному образу действий. Строгое соответствие (где, очевидно, может быть) между конфигурациями Заказчиков - находка. Очевидно, что продукты меняются, поэтому мы собираемся обсуждать новые продукты / версии и т. Д. И выбираем последовательную стратегию конфигурации перед развертыванием. Это не масштабируется для крупной компании, но, честно говоря, я вижу в этом особенность, а не ошибку. (Я не стану разглагольствовать о более крупных компаниях, предлагающих управляемые услуги, с их сотрудниками «инженерами» и ужасной тенденцией к одноразовым, неполноценным «решениям» и несоответствиям между Заказчиками ...> улыбка <)
я яростно против «страшного связующего». Я никогда не видел, чтобы физическая документация обновлялась Когда-либо. Я считаю, что тратить время на создание физических копий документации - это пустая трата денег Заказчика. Я бы предпочел потратить время на разработку того, как создать документацию на основе «живых» данных из запущенных конфигураций.
В качестве примера я обязательно не вести электронные таблицы с информацией об IP-адресах. Для этого нужны DHCP и DNS (подробности см. Ниже). Если эти вещи не работают, у нас большие проблемы.
У нас были клиенты, которые просили «создать документ, показывающий всю конфигурацию нашей групповой политики», и я упал на пятки и отказался это сделать. Мое повторяющееся встречное предложение (которое до сих пор работало) заключалось в том, чтобы познакомить Заказчика с инструментами администрирования, которые могут дать ему «самообслуживание» или использовать программное обеспечение для создания «живой» удобной для клиента документации по запросу.
Мы очень стараемся излагать вещи простым английским языком. Нетехнический ИТ-контакт может, например, проверить членство компьютера в группе Active Directory и увидеть такие вещи, как «Программное обеспечение - Установка Microsoft Office 2010 Pro» и «Групповая политика - Автоматический вход в систему киоска для доставки». Чтобы объяснить, что это означает, не требуется никакой документации.
Вот некоторые «живые» данные, которые мы используем:
Все Распределение IP-адресов хранится на DHCP-серверах, включая устройства со статической адресацией (отмеченные как таковые в комментариях). MAC- и IP-адреса можно легко запросить с помощью сценариев или вручную, и, по определению, данные должны быть актуальными, если они используются в производственной среде.
Все получает имя и PTR-запись в DNS. Большинство хостов также получают запись HINFO. Вещи, требующие подробного описания, получают запись в формате TXT.
Обильное и подробное использование полей «Примечания» везде, где это возможно - Active Directory, описания компьютеров, описания общих папок и т. Д. Мы также многословны и ясны в отношении таких вещей, как имена групп безопасности.
Комментарии / примечания в конфигурациях сетевого оборудования (например, комментарии к спискам ACL, описания портов, расположение / контактная информация SNMP).
Я довольно отрицательно отношусь к идее хранения информации в произвольной форме в таких вещах, как текстовые файлы, вики и т. Д. Структура способствует хорошему поиску. Всякий раз, когда я могу заставить механизм структурированного хранения работать на меня (даже если это означает, что мне нужно написать программное обеспечение для его запроса), я предпочитаю его. Комментарии, которые я могу проанализировать из файлов конфигурации, баз данных и т. Д., Всегда меня привлекают, когда сопоставляются с документами, сгенерированными вручную, которые почти сразу устаревают.
Когда нам нужно хранить информацию в «свободной форме», мы используем наш собственный репозиторий SVN. Он содержит всю разнообразную статическую документацию, которую мы создавали за многие годы и хранимую Заказчиком. Мы используем SVN для этого с 2004 года, и он отлично зарекомендовал себя как инструмент для совместной работы. Мы редактируем схемы баз данных, сценарии системного администратора, резервные копии объектов групповой политики и т. Д. Я пытаюсь проверить все, что могу, в системе контроля версий.
Искать в моей кассе очень легко с помощью инструментов индексирования на основе файловой системы. Я знаю, что у каждого из нас есть как минимум одна полная копия репозитория, доступная нам локально в любое время. Мы также сделали репозиторий доступным через аутентифицированный WebDAV через SSL на случай, если нам абсолютно необходимо получить доступ к данным, хранящимся там, и иметь доступ только через браузер.
Нас никогда не просили сделать это, но мы были бы счастливы создать учетную запись на сервере SVN, чтобы позволить Клиенту оформлять заказ и взаимодействовать со своими собственными файлами (если у них есть внутренний ресурс, который так склонен ). Мы используем стандартизированный формат для хранения всей статической документации для клиентов (документация по лицензиям на программное обеспечение, записи о покупках и т. Д.), Что не требует пояснений.
Наряду с репозиторием SVN мы также самостоятельно размещаем нашу электронную почту. Вся входящая / исходящая электронная почта архивируется с тех пор, как домен компании начал получать электронную почту. Он доступен в виде журналов BSMTP партнерам для справки (и лично я считаю его бесценным). Ситуация так и не возникла, но я знаю, что мы были бы счастливы предоставить Клиенту доступ к журналам любой корреспонденции от их сотрудников, если они когда-либо попросят. Обеспечить внутреннюю коммуникацию между партнерами будет сложнее, потому что мы вполне можем ссылаться на нескольких клиентов в одном сообщении. (Возможно, нам следовало бы поступить лучше, но мы этого не сделали.)
Пароли - одна из основных "бородавок" в нашем процессе. Мы используем индивидуальные репозитории, защищенные паролем (с уникальными комбинациями) для каждого Клиента, чтобы предоставить Клиенту доступ к безопасному файлу. Мы храним мастер-пароли для всех безопасных файлов в другом безопасном файле с комбинацией, известной только партнерам. Эта часть действительно требует доработки. Я думаю, мы хотели бы, чтобы каждый Заказчик размещал локальное хранилище учетных данных с использованием настоящего многопользовательского приложения для хранилища паролей (с контрольным журналом и т. Д.), Но мы уже почти 10 лет отбрасываем эту идею .
Наши записи учета рабочего времени тщательно детализированы и предоставляются клиентам в любом электронном формате, который они хотят (до этого момента это были текст ASCII и PDF). Клиенты получают время начала / окончания каждого оплачиваемого события и подробное описание выполненной работы. Мы считаем эти служебные записки очень ценными для внутреннего пользования, поскольку они позволяют нам быть в курсе того, что происходит на сайтах клиентов наших партнеров. В случае возникновения проблемы эти записи дают нам основанную на знаниях информацию обо всех предыдущих проблемах и решениях, с которыми мы столкнулись за эти годы. Мне не стыдно сказать, что я решил проблемы для одного Клиента, найдя заметки, которые я забыл написать для другого Клиента много лет назад.
Небольшое предостережение в сторону повторного создания документации: на моей «старой работе» (работая на кого-то еще несколько лет назад) компания подала в суд на неплательщика. В итоге мы оказались в стороне от встречного иска от неплательщика. Наши внутренние записи и электронная почта касательно этого Клиента были вызваны в суд и разоблачены. Этот опыт научил меня много о том, чтобы не хранить на фиксированном носителе ничего такого, что вы не хотите обнародовать.
Я написал несколько писем с некоторыми (эээ) выбор слова и фразы в них о моем разочаровании этим Заказчиком и некоторыми другими «инженерами» в моей компании. Мне совсем не нравилось подвергаться перекрестному допросу в открытом суде.
Когда мы начали наш текущий бизнес, партнеры договорились, что все фиксированные записи (электронная почта, текстовые сообщения, голосовая почта, файлы в репозитории SVN, рабочие записи в счетчике рабочего времени и т. д.) будут всегда считаться «ориентированными на клиента» - даже если они никогда не предназначались для того, чтобы попасть в список клиентов. ' Руки. Это было сложно сделать и требовало много дисциплины, но я думаю, что оно того стоит. Мы, безусловно, хотим создать атмосферу профессионализма для наших клиентов, и жить в соответствии с ней - вот способ сделать это. Я, конечно, никогда не буду смущен, как будто я снова был в этом зале суда.
Для получения основной информации, подобной описанной вами (за исключением сетевой диаграммы), мы используем одну книгу Excel и сохраняем ее в сетевой папке с именем клиента. Хотя я могу понять, почему людям не нравится этот подход, я считаю, что он отлично работает, потому что это единый справочный документ, который я могу взять с собой на сайт, отправить по электронной почте и быстро обновить.
Моя самая большая жалоба - отсутствие контроля версий, но я еще не нашел ничего, что бы хорошо работало, не усложняя жизнь.
Чтобы противостоять вашему "Я стремлюсь к процессу, более портативному, безопасному и элегантному, чем простая таблица":
Более портативный: что жестяная банка быть более портативным, чем таблица на 500 килобайт? Я бы побоялся использовать что-либо в облаке или в Интернете, потому что подключение к Интернету не может быть гарантировано.
Надежность: это я дам вам, и мне тоже нужны решения, которые сделают наше решение более безопасным.
Элегантно: мы потратили время на создание хорошего шаблона для нашей книги. Как я уже сказал, это рабочая тетрадь на нескольких листах, а не просто огромная страница с разрозненной информацией. Я думаю, что большая часть ИТ-документации хорошо вписывается в табличную форму, а электронные таблицы делают это очень аккуратным и простым.
Хотя у меня много проблем с тем, как мы записываем и храним документацию по сборке, я действительно не могу найти недостатки в прочной, хорошо отформатированной электронной таблице. Также добавлю, что мы работаем с некоторыми большой Компании, оказывающие ИТ-услуги, работают примерно одинаково. Опять же, это великолепно - я захожу на сайт, запрашиваю документацию и получаю одну аккуратную электронную таблицу, которую я могу использовать в течение всего времени.
Большое преимущество этого устрашающего связующего:
Какую бы цифровую систему вы ни использовали, больше не имеет значения, если вы дисциплинируете себя обновлять подшивку всякий раз, когда делаете что-то стоящее.
И связующее, конечно, совершенно бесполезно для вас, если вы делаете почти всю свою поддержку удаленно.
Я был большим поклонником вики, потому что она проста в обслуживании, легко отслеживаются гиперссылки на интерфейсы ILO и управления, удаленный рабочий стол и вход по SSH. Свободная форма подходит для большинства информации, которую я хотел бы иметь:
описание сайта: «сетевой принтер (МФУ OKI 1234) находится рядом с столом Джона, струйный принтер HP модели 0123 находится в Бобе, в офисе босса» значительно упрощает ответ на телефонный звонок: «мы закончились чернила, какой картридж заказать снова? ».
страница для каждого устройства, в идеале с изображением, типом и конфигурацией, его назначением и т. д.
Для Wiki есть несколько достойных модулей экспорта для создания бумажных или цифровых документов для передачи и включения в эту ужасную папку.
Я согласен с Дэном в том, что Excel - хорошее портативное решение, и я думаю, что он является отличным аргументом в пользу этого, за исключением части безопасности, где я думаю, что беспокойство несколько неверно:
Каким бы методом вы ни хотели распространять, может быть предусмотрено безопасное решение (например, зашифрованная электронная почта, защищенное общее хранилище и т. Д.). То же самое и с контролем версий (например, теневые копии, svn и т. Д.).
Однако просто в качестве конструктивной критики и со всем уважением я бы добавил, что основным недостатком общей электронной таблицы Excel является ее ограничения параллелизма. В тот день, когда у вас будет два или более администраторов, они сочтут королевской болью вынужденный выбор между возможностью открывать лист для редактирования только по одному или сохранением нескольких копий, которые затем необходимо объединить (какие данные актуальный, а какой нет?). И это действительно боль.
Лучшее решение - использовать Excel (или что угодно) в качестве интерфейса для небольшой базы данных по выбору, будь то Access (просто для обеспечения переносимости), MS SQL, MariaDB или что-то еще, что вам нравится.
Я защищаю это как решение, которое не только подходит для передачи информации другой стороне (= Excel), но также подходит для поддержания постоянной документации.
Вкратце, я считаю, что даже с несколькими администраторами (не говоря уже о более крупных магазинах) отдел, использующий Excel для хранения данных документации, является отделом с обширной документацией. Никогда еще не видел исключения, если нет только одного администратора.
Но отдел, использующий хранилище на основе базы данных, имеет возможность хранить полную и актуальную документацию. Тогда это только вопрос усилий. Excel - это работоспособный интерфейс базы данных со своими плюсами и минусами, но ни в коем случае не единственный вариант.
Возможно, это не совсем то, что вы ищете, но вот что я делаю.
Я использую Microsoft Office для создания всех документов для каждого из моих клиентов. Я использую Excel (информация об IP-адресе, сопоставление портов коммутатора, макет стойки), Word (информация о конфигурации, счета-фактуры, шаблоны SOW) и Visio (диаграммы). Я создаю иерархию папок с родительской папкой с именем Consulting и дочерней папкой с именем для каждого клиента. Когда я создаю или обновляю клиентские документы, я синхронизирую их со своим iPhone (используя Документы на вынос), USB-накопитель и учетную запись DropBox (с использованием двухфакторной аутентификации). Таким образом, у меня будет доступ ко всей документации (так или иначе) в любом месте и в любом месте.
Я также использую приложение для управления проектами / отчетности / выставления счетов / учета рабочего времени под названием OfficeTime. Есть приложение для iPhone и сопутствующее приложение для Windows, поэтому у меня есть доступ к информации о проекте, счетам, часам и т. Д. На моем iPhone, когда я нахожусь на сайте, и синхронизирую со своим рабочим столом, когда я возвращаюсь домой.
Хотя это не идеальное решение, но вам стоит взглянуть на Устройство42.
Вот что вы можете сделать: IP-адреса и устройства могут быть связаны с клиентами. И у вас могут быть группы VRF для перекрытия диапазонов IP для разных клиентов.
У него нет детальных разрешений для IP-адресов / устройств (только доступ на основе глобальных ролей), поэтому вы не можете разрешить прямой доступ конечным клиентам. Но вы можете создавать отчеты для клиентов с информацией об устройстве и IP-адресе и при необходимости отправлять их конечному клиенту.
Это, по крайней мере, даст вам интерфейс для организации всей информации в центральном репозитории. Вы можете хранить информацию об активах, информацию об IP, информацию о контракте и пароли.
Кроме того, он предоставляет большую часть информации о вызовах REST API, но не уверен, что вы можете подключить что-то для отдельных клиентов на основе этого.
