Консалтинг: организация документации сайта / среды для клиентов? [закрыто]

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

• Какие статические IP-адреса я могу использовать для устанавливаемых нами новых сетевых часов?
• Как поместить исключение в веб-фильтр? Генеральный директор больше не может попасть на сайт NRA !!
• Нам нужно выключить сервер Linux для планового отключения электроэнергии. Что за команда снова?

Это малые предприятия и, как правило, не имеют специального технического персонала. В рамках одной компании Wiki / Confluence / Sharepoint и т. Д. Имеют смысл в качестве центрального хранилища документации и информации об окружающей среде, но я пытаюсь найти последовательный способ доставки этой информации отдельным клиентам.

Я стреляю по процессу, который более переносим, ​​безопасен и элегантен, чем простая электронная таблица или страшное переплетное устройство, полное устаревшей информации .

• Важные IP-адреса, область DHCP и т. Д.
• Схема сети (при необходимости).
• Административные имена пользователей и пароли, а также URL-адреса управления.
• Лицензионные ключи программного обеспечения.
• Поддержка контрактов и гарантийная информация.
• Поставщик поддержки контакты и инструкции.

Я знаю, что здесь есть и другие консультанты. Любые предложения или советы по ведению документации в различных средах в удобном для пользователя формате? Как ты это делаешь?

Я являюсь партнером в контрактной / консалтинговой службе из трех человек с июня 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 года, и он очень хорошо работал как инструмент для совместной работы. Мы создаем схемы баз данных, сценарии sysadmin, резервные копии объектов групповой политики и т. Д. Я пытаюсь проверить все, что могу, в управлении версиями.

Очень легко найти мою кассу с помощью инструментов индексации на основе файловой системы. Я знаю, что у каждого из нас есть по крайней мере одна полная копия хранилища, доступная нам локально в любое время. Мы также сделали хранилище доступным через аутентифицированный WebDAV по SSL на случай, если нам абсолютно необходимо получить доступ к хранящимся там данным и иметь доступ только через браузер.

Нас никогда не просили сделать это, но мы были бы рады создать учетную запись на сервере SVN, чтобы позволить Клиенту извлекать информацию и взаимодействовать со своими собственными файлами (если у них есть внутренний ресурс, который так склонен) ). Мы используем стандартизированный формат для хранения всей статической документации Заказчика (документация по лицензии на программное обеспечение, записи о закупках и т. Д.), Которая довольно понятна.

Наряду с SVN-репозиторием мы также самостоятельно размещаем нашу электронную почту. Вся входящая / исходящая электронная почта была заархивирована, так как домен компании начал получать электронную почту. Это доступно как журналы BSMTP партнерам для справки (и, лично я нашел, что это неоценимо). Ситуация никогда не возникала, но, я знаю, мы были бы рады предоставить Заказчику доступ к журналам любой корреспонденции их сотрудникам, если они когда-либо спросят. Обеспечение внутренней коммуникации между партнерами было бы более трудным, потому что мы могли бы ссылаться на нескольких клиентов в одном сообщении. (Вероятно, мы должны быть лучше об этом, но мы не были.)

Пароли являются основной «бородавкой» в нашем процессе. Мы используем отдельные репозитории «Safe Password» (с уникальными комбинациями) для каждого Клиента, чтобы разрешить обмен безопасным файлом с Клиентом. Мы храним мастер-пароли для всех безопасных файлов в другом безопасном файле, комбинация которого известна только партнерам. Эта часть действительно нуждается в некоторой работе. Я думаю, что мы хотели бы, чтобы каждый Заказчик размещал хранилище учетных данных на месте, используя реальное многопользовательское приложение для хранения паролей (с контрольным журналом и т. Д.), Но мы разворачивали эту идею почти 10 лет назад ,

Наши записи учета рабочего времени тщательно детализированы и предоставляются Заказчикам в любом электронном формате, который они хотят (который до этого момента был в формате ASCII и в формате PDF). Клиенты получают время начала / окончания каждого оплачиваемого события и подробное описание выполненной работы. Мы считаем эти сервисные замечания очень ценными для внутреннего использования, поскольку они позволяют нам быть в курсе того, что происходит на сайтах клиентов партнеров. В случае возникновения проблем эти записи дают нам основанные на знаниях все предыдущие проблемы и решения, с которыми мы столкнулись за эти годы. Мне не стыдно сказать, что я решил проблемы для одного клиента, найдя заметки, которые я забыл написать для другого клиента много лет назад.

Быстрое и предупреждающее замечание по поводу: производства документации: На моей «старой работе» (работавшей на кого-то еще несколько лет назад) компания подала в суд на неоплачиваемого Клиента. В итоге мы оказались в бизнес-положении по встречному иску от неоплачиваемого Клиента. Наши внутренние записи и электронная почта о том, что Клиент был вызван в суд и предъявлен в суде. Этот опыт научил меня много о чем не хранить в неподвижной среде , что вы не хотите быть обнародованы.

Я написал несколько писем с некоторыми (ERM) выбор слов и фраз в них о своих разочарованиях с этим Клиентом и с некоторыми другими «инженеров» в моей компании. Мне вообще не нравилось подвергаться перекрестному допросу об этих вещах в открытом суде.

Когда мы начинали наш текущий бизнес, партнеры согласились, что все фиксированные записи (электронная почта, текстовые сообщения, голосовая почта, файлы в репозитории SVN, рабочие записи в трекере времени и т. Д.) Будут постоянно рассматриваться как «ориентированные на клиента» - даже если они никогда не предназначались для того, чтобы оказаться в руках Клиентов. Это было трудно сделать и требует большой дисциплины, но я думаю, что оно того стоит. Мы, безусловно, хотим создать атмосферу профессионализма для наших клиентов, и жить так - это способ сделать это. Я, конечно, никогда не буду смущен, как я снова был в этом зале суда.

Для основной информации, которую вы описываете (за исключением сетевой диаграммы), мы используем одну книгу Excel и сохраняем ее в сетевой папке с именем клиента. Хотя я могу понять, почему людям не нравится этот подход, я считаю, что он отлично работает, потому что это единый справочный документ, который я могу взять с собой на сайт, по электронной почте и быстро обновлять.

Моя самая большая жалоба - отсутствие контроля версий, но мне еще предстоит найти что-то, что хорошо работает, не делая жизнь тяжелой работой.

Чтобы противостоять вашему «я стреляю в процесс, который является более портативным, безопасным и элегантным, чем простая электронная таблица»:

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

Безопасный: этот, который я дам вам, и я тоже хотел бы найти решения для повышения безопасности нашего решения.

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

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

Большое преимущество этого страшного переплета:

• Нетехнические клиенты могут понять это, сохранить его на месте и сохранить в безопасности, как они привыкли и уже делают со всеми видами других важных документов.
• Ваши клиенты могут легко сдать его в случае, если они наймут вам замену, профессиональную работу и то, что могло бы дать вам быстрый старт и дать вам справку, когда вы получили их в качестве клиентов.
• Простой журнал обслуживания в начале с основными моментами каждого посещения сайта - это нечто осязаемое.
• Папка также содержит CD / DVD и сертификаты с лицензионными кодами и ключами активации на случай, если BSA или другой поставщик посетит.

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

И переплет, конечно, совершенно бесполезен для вас, если вы оказываете почти всю свою поддержку удаленно.

Я был большим поклонником использования вики, потому что он прост в обслуживании, легко отслеживаются гиперссылки на ILO и интерфейсы управления, логины удаленного рабочего стола и SSH. Freeform подходит для большей части информации, которую я хотел бы иметь:

• Описание сайта: «Сетевой принтер (OKI 1234 MFP) находится рядом со столом Джона, струйный принтер HP модели 0123 сидит в Бобсе, офис начальника», что значительно упрощает ответ на телефонный звонок: «мы закончились чернила, какой картридж мы должны заказать снова? ".

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

• Есть несколько приличных экспортных модулей для вики, чтобы генерировать печатные или цифровые документы для передачи и включения в эту страшную папку

Я согласен с тем, что Дэн в Excel является хорошим переносимым решением, и я думаю, что он отлично подходит для этого, за исключением части, касающейся безопасности, где, как мне кажется, беспокойство несколько неверно направлено:

Независимо от метода, который вы хотите распространять, может быть предусмотрено защищенное решение (например, зашифрованная электронная почта, защищенное общее хранилище и т. Д.). То же самое верно для контроля версий (например, теневые копии, svn и т. Д.).

Тем не менее, просто с помощью конструктивной критики и со всем уважением я бы добавил, что основным недостатком совместно используемой электронной таблицы Excel являются ее ограничения параллелизма. В тот день, когда у вас будет два администратора или больше, они сочтут огромной болью быть вынужденными сделать выбор: либо только по одной за раз, когда можно открыть лист для редактирования, либо сохранить несколько копий, которые затем нужно объединить (какие данные в курсе, а что нет?). И это действительно боль.

Лучшее решение - использовать Excel (или что угодно) в качестве интерфейса для небольшой базы данных по выбору, будь то Access (просто для решения вопросов переносимости), MS SQL, MariaDB или что-то еще, что вам нравится.

Я рекомендую это как решение, которое не только подходит для передачи информации другой стороне (= Excel), но также подходит для поддержки текущей документации.

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

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

Это может быть не совсем то, что вы ищете, но вот что я делаю.

Я использую Microsoft Office для создания всех документов для каждого из моих клиентов. Я использую Excel (информация об IP-адресе, отображение портов коммутатора, расположение стойки), Word (информация о конфигурации, счета, шаблоны SOW) и Visio (диаграммы). Я создаю иерархию папок с родительской папкой с именем Consulting и дочерней папкой с именем для каждого клиента. При создании или обновлении клиентских документов я синхронизирую их с моим iPhone (используя Documents To Go ), флэш-накопитель USB и учетную запись DropBox (с использованием двухфакторной аутентификации). Таким образом, у меня есть доступ ко всей документации (так или иначе), куда бы я ни пошел.

Я также использую приложение для управления проектами / отчетности / выставления счетов / отслеживания времени под названием OfficeTime . Есть приложение для iPhone и сопутствующее приложение для Windows, поэтому у меня есть доступ к информации о проекте, выставлению счетов, часам и т. Д. На моем iPhone, когда я нахожусь на сайте, и синхронизации с моим рабочим столом, когда я возвращаюсь домой.

Хотя это не идеальное решение, но вы должны взглянуть на Device42 .

Вот что вы можете сделать: IP-адреса и устройства могут быть связаны с клиентами. И у вас могут быть группы VRF для перекрывающихся диапазонов IP для разных клиентов.

Он не имеет детального разрешения для IP-адресов / устройств (только глобальный доступ на основе ролей), поэтому вы не можете разрешить конечным клиентам прямой доступ. Но вы можете создавать отчеты по клиентам с информацией об устройстве и IP и отправлять их конечному клиенту при необходимости.

По крайней мере, это даст вам интерфейс для организации всей информации в центральном хранилище. Вы можете хранить информацию об активе, информацию об IP, информацию о контракте и пароли.

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