Comments 33
Схему нужно скачивать из вики, менять и заливать обратно.
Так есть же плагины, на лету генерирующие схему из текста. Например, graphviz. А тут можно поискать и альтернативы ему.
А вы «это» пробовали? Я пробовал, на сколько-нибудь больших схемах голову сломаешь.
Мы «это» пробовали. Вместо одной большой схемы делаете несколько маленьких. Причём можно внутри схемы сделать блоки описывающие разные сервера/сервисы кликабельными и ведущими на доку по этим серверам/сервисам.
И вообще, насчёт «голову сломаешь» — это не вопрос использования graphviz, это вопрос того насколько лично Вы в состоянии ясно и в нужном разрезе описать схему(ы) взаимодействия ваших объектов. Потренировавшись можно подобрать такой подход к описанию этих схем, что он не только будет удобен как схема-картинка, но и вполне прост и понятен в текстовом виде (т.е. его легко править) плюс пригоден к grep-анию и прочему автоматизированному анализу.
И вообще, насчёт «голову сломаешь» — это не вопрос использования graphviz, это вопрос того насколько лично Вы в состоянии ясно и в нужном разрезе описать схему(ы) взаимодействия ваших объектов. Потренировавшись можно подобрать такой подход к описанию этих схем, что он не только будет удобен как схема-картинка, но и вполне прост и понятен в текстовом виде (т.е. его легко править) плюс пригоден к grep-анию и прочему автоматизированному анализу.
Если есть возможность, приведите пожалуйста пример нескольких таких схем, обезличенных конечно же. Я бы хотел убедиться в своей неправоте по поводу тектовых схем и понять, как их можно использовать в действительности.
Вот пример достаточно сложной схемы описывающей наш сервис авторизации и аутентификации, который по RPC используется другими проектами: png, source. И, надо отметить, исходник в каком-то смысле читается даже легче, чем схема. :) Для лучшего понимания схемы вот ещё легенда к ней: png, source. У легенды исходник читается сложнее, т.к. он слишком абстрактный и там слишком много разных типов объектов и связей.
Схема нам чаще нужна как инфографика — в одном представлении увидеть наложения разных данных — это совокупность многих документов.
Мало смысла генерить схему по одному небольшому документу — его и так можно охватить взглядом.
Мало смысла генерить схему по одному небольшому документу — его и так можно охватить взглядом.
Ну так и пишите, что у вас схемы на 100500 элементов. Что вы пробовали плагин такой-то, и столкнулись с тем-то и тем-то, а требования такие-то. Иначе вас можно неправильно понять — что в вики в принципе невозможно вести схемы.
Зачем 100500, уже на десятках становится сложно.
Вот есть например замечательная программа yed. По удобству это лучший редактор графов и построитель схем который я знаю, мне лично им намного удобнее пользоваться чем даже Microsoft Visio. Он отлично продуман, очень удобен и для больших и сложных схем рулит и педалит. Кстати, он написан на java и его можно при известной сноровке встроить в вики в виде апплета. Вот это было бы нормальное, полноценное решение.
Предложенный же вами плагин весьма неудобен в использовании, и схемы тех размеров, которые можно его с помощью создать, отлично заменяются текстом.
Вот есть например замечательная программа yed. По удобству это лучший редактор графов и построитель схем который я знаю, мне лично им намного удобнее пользоваться чем даже Microsoft Visio. Он отлично продуман, очень удобен и для больших и сложных схем рулит и педалит. Кстати, он написан на java и его можно при известной сноровке встроить в вики в виде апплета. Вот это было бы нормальное, полноценное решение.
Предложенный же вами плагин весьма неудобен в использовании, и схемы тех размеров, которые можно его с помощью создать, отлично заменяются текстом.
>Если что-то можно не писать, потому что оно уже где-то есть, то не пишите
Меня всегда убивала документация, где для понимания смысла абзаца надо сходить по 10 ссылками из него (а там еще по 10 ссылкам). Не уж, надо хотябы кратко, но дублировать информацию.
Меня всегда убивала документация, где для понимания смысла абзаца надо сходить по 10 ссылками из него (а там еще по 10 ссылкам). Не уж, надо хотябы кратко, но дублировать информацию.
BOFH!
А по теме — да, вполне себе хороший вариант. Более того, у него есть ещё одно преимущество, если в начале поставить дату редактирования и ссылку на страницу в вики, то вполне можно это хозяйство сохранить на самом сервере в обычном txt. Что позволит иметь крупицу данных для анализа и (при необходимости восстановления) даже если вики канет в лету по любой причине.
Чёрт, оказывается в статье это уже есть (/etc/motd). Тогда, тогда…
О! Знаю! ТАКИЕ конфиги — можно просто распечатать (даже на Epson LQ-100, хехе) и убрать на удалённую площадку. Осталось понять зачем =)
Чёрт, оказывается в статье это уже есть (/etc/motd). Тогда, тогда…
О! Знаю! ТАКИЕ конфиги — можно просто распечатать (даже на Epson LQ-100, хехе) и убрать на удалённую площадку. Осталось понять зачем =)
У схем и прочих векторных по сути рисунков есть ещё один важный недостаток — редактировать bmp/png/gif сложно, а другое браузеры не отображают. То есть нам нужно хранить и оригинал в формате (графического?) редактора, и экспорт оригинала в растр, понимаемый браузерами. И не только хранить, но и не забывать синхронизировать. Есть, конечно, SVG, но не всегда он применим.
А вообще не вики единой. Те же возможности (групповая работа, история правок, использование везде(?) ) и даже больше (ветви, слияние, тэги, хуки и т. п.) дают VCS. И, имхо, позволяют более удобно автоматизировать поддержку актуальности документации. Что-то вроде: по коммиту или пушу в /etc вызывается sed, который заменяет старый конфиг (или его фрагмент) в документации, которая тоже под управлением VCS и коммитится после замены, о чём ответственным отправляется уведомление по мылу. Вероятно подобный сценарий можно реализовать и с помощью вики, но мне кажется сложнее чем пятком строк скрипта.
А вообще не вики единой. Те же возможности (групповая работа, история правок, использование везде(?) ) и даже больше (ветви, слияние, тэги, хуки и т. п.) дают VCS. И, имхо, позволяют более удобно автоматизировать поддержку актуальности документации. Что-то вроде: по коммиту или пушу в /etc вызывается sed, который заменяет старый конфиг (или его фрагмент) в документации, которая тоже под управлением VCS и коммитится после замены, о чём ответственным отправляется уведомление по мылу. Вероятно подобный сценарий можно реализовать и с помощью вики, но мне кажется сложнее чем пятком строк скрипта.
Что касается использования вики, то у этого подхода есть один довольно важный недостаток: в качестве текстового редактора вики используют textarea в браузере, и этот редактор катастрофически менее удобен, надёжен, привычен и функционален чем основной текстовый редактор используемый админами/разработчиками (вроде Vim/Emacs). Textarea в браузере годится для комментирования, максимум для редкого написания небольших статей. А документации обычно приходится писать довольно много, причём не редко нужно проводить над ней массовые операции поиска/замены — всё это делать на веб-страничках с вики крайне неудобно. И практика показывает, что удобство написания документации это один из ключевых факторов — доку и так никто писать не любит, а если её писать ещё и не удобно, то её вообще избегают писать.
Поэтому на мой взгляд документацию гораздо удобнее писать в обычных текстовых файлах. Версионирование обеспечивать любой системой контроля версий. А веб-сайт документации может работать в режиме read-only просто показывая документацию с красивыми стилями и автоматически сгенерированными схемами.
Более детально я описал наш подход в статье Использование asciidoc для документирования проекта.
Поэтому на мой взгляд документацию гораздо удобнее писать в обычных текстовых файлах. Версионирование обеспечивать любой системой контроля версий. А веб-сайт документации может работать в режиме read-only просто показывая документацию с красивыми стилями и автоматически сгенерированными схемами.
Более детально я описал наш подход в статье Использование asciidoc для документирования проекта.
Хороший подход, добавил его в конец статьи. Единственное замечание:
Вместо textarea всегда можно использовать костыль наподобие такого: addons.mozilla.org/en-US/firefox/addon/its-all-text/ Таким образом я довольно большую часть текстов набираю в vim.
Что же касается глобальных поиска и замены, то набор файликов и VCS удобнее всего.
Что касается использования вики, то у этого подхода есть один довольно важный недостаток: в качестве текстового редактора вики используют textarea в браузере, и этот редактор катастрофически менее удобен, надёжен, привычен и функционален чем основной текстовый редактор используемый админами/разработчиками (вроде Vim/Emacs).
Вместо textarea всегда можно использовать костыль наподобие такого: addons.mozilla.org/en-US/firefox/addon/its-all-text/ Таким образом я довольно большую часть текстов набираю в vim.
Что же касается глобальных поиска и замены, то набор файликов и VCS удобнее всего.
Поговорил с ребятами, в пользу вики есть еще несколько аргументов:
— Если с документацией работают не только разработчики, то намного проще использовать вики
— В вики легче привести документацию к одному виду, не будет разброда и шатания (из опыта)
— К вики легко приделываются роботы, так что преимущества репозитория неочевидны
— Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексы
Есть и недостатки, например если уже есть документация в html-формате ее за минуту к вики не подошьешь.
В целом, всегда нужно выбирать по обстоятельствам. Если в команде одни разработчики и есть четкие стандарты на все — репозитарий, если не только разработчики или плохо со стандартами — вики.
— Если с документацией работают не только разработчики, то намного проще использовать вики
— В вики легче привести документацию к одному виду, не будет разброда и шатания (из опыта)
— К вики легко приделываются роботы, так что преимущества репозитория неочевидны
— Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексы
Есть и недостатки, например если уже есть документация в html-формате ее за минуту к вики не подошьешь.
В целом, всегда нужно выбирать по обстоятельствам. Если в команде одни разработчики и есть четкие стандарты на все — репозитарий, если не только разработчики или плохо со стандартами — вики.
Если с документацией работают не только разработчики, то намного проще использовать викиНа самом деле технически эти два подхода совершенно не конфликтуют, а отлично дополняют друг-друга. Текстовые файлы в репозитории всё-равно пишутся используя вики-подобную разметку (asciidoc, markdown, etc.) и доступны для просмотра через сайт (что даёт красивое/наглядное форматирование текста, встроенные схемы/картинки, и работающие гиперссылки), и никто не мешает реализовать их редактирование через сайт как обычную вики (с commit-ом в репозиторий каждого изменения странички через веб-интерфейс). Такую документацию можно читать/писать и в обычных файлах и через сайт, и каждый может использовать тот способ, который лично ему удобнее.
В вики легче привести документацию к одному виду, не будет разброда и шатанияРазброд и шатание в данном случае (когда хоть в текстовом файле хоть в вики можно писать что и как угодно, нет жёсткой формы для ввода данных) никак не зависят от используемого технического решения.
К вики легко приделываются роботыДа ладно. Роботов гораздо проще приделать к каталогу с текстовыми файлами, чем к веб-сайту.
Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексыЯ не слышал о проектах, по которым столько документации, что grep по ней настолько тормозит что для ускорения поиска нужны индексы. Но, в любом случае, как я уже говорил выше, индексация как часть фич вики-интерфейса никак не конфликтует с работой с докой как с файлами.
В целом, всегда нужно выбирать по обстоятельствам.Разумеется.
> На самом деле технически эти два подхода совершенно не конфликтуют, а отлично дополняют друг-друга. (...)
А как реализовано редактирование страниц из браузера?
> Разброд и шатание в данном случае (когда хоть в текстовом файле хоть в вики можно писать что и как угодно, нет жёсткой формы для ввода данных) никак не зависят от используемого технического решения.
Как показывает практика, зависят. Непрограммистам с вики жить легче. Хотя, возможно это у меня такая выборка.
> Да ладно. Роботов гораздо проще приделать к каталогу с текстовыми файлами, чем к веб-сайту.
Я об этом написал в UPDATE к статье.
А как реализовано редактирование страниц из браузера?
> Разброд и шатание в данном случае (когда хоть в текстовом файле хоть в вики можно писать что и как угодно, нет жёсткой формы для ввода данных) никак не зависят от используемого технического решения.
Как показывает практика, зависят. Непрограммистам с вики жить легче. Хотя, возможно это у меня такая выборка.
> Да ладно. Роботов гораздо проще приделать к каталогу с текстовыми файлами, чем к веб-сайту.
Я об этом написал в UPDATE к статье.
А лучше пойти еще дальше. Использовать chef (puppet etc) и ваша конфигурация становится вашей документацией, а еще бекапом. В дополнение к этому получаем тестирование, контроль версий и многое другое. DevOpts решает.
Конфигурация =/= документация. Вы же не будете говорить, что сам исходный код является докуменацией на себя?
Я систему управления конфигурацией упомянул в статье.
Я систему управления конфигурацией упомянул в статье.
Вот как раз об этом я и говорю. Он становится документацией и это очень здорово работает. Мы постоянно включаем новых людей в инфраструктуру проектов (десятки проектов, десятки серверов), причем все чаще самих разработчиков, т.к. по сути управление конфигурацией становится программированием.
Но, естественно, документация не исключается, просто ее необходимость (и объем) возникает несравненно реже.
Получается, что документировать конфигурацию нужно также, как код. Плюс, многие общие вещи из конфигов не ясны, нужно делать отдельное описание архитектуры. Это особенно актуально для «десятки проектов, десятки серверов», потому что иначе взаимодействие всего со всем превращается в дикую кашу, которую никто не понимает. Сталкивался :)
Мы используем для работы с документацейи Google Docs:
1) Удобный редактор
2) Доступ отовсюду
3) Расшаривание (ридонли и с возможностью редактирования)
4) Командная работа
5) Хранение версий
6) Комментирование участков текста
7) Встроенные схемы (со всеми вышеперечисленными плюшками)
8) Экспорт в doc, pdf или публикация в виде html
Вроде всё что нужно.
P.S. Да и недавно запущенный google drive добавляет плюсов в виде прикрепления файлов и синхронизацией с десктопом.
1) Удобный редактор
2) Доступ отовсюду
3) Расшаривание (ридонли и с возможностью редактирования)
4) Командная работа
5) Хранение версий
6) Комментирование участков текста
7) Встроенные схемы (со всеми вышеперечисленными плюшками)
8) Экспорт в doc, pdf или публикация в виде html
Вроде всё что нужно.
P.S. Да и недавно запущенный google drive добавляет плюсов в виде прикрепления файлов и синхронизацией с десктопом.
Для среднекрупных компаний это решение неприемлемо просто в силу факта хранения данных на серверах google.
Кроме того, как я уже писал документация частично пишется роботами. Насколько просто прицепить роботов к googledocs?
Кроме того, как я уже писал документация частично пишется роботами. Насколько просто прицепить роботов к googledocs?
Sign up to leave a comment.
Еще раз о документации