Разрабатываем документацию с помощью NPJ: эффективно и удобно!

АЛЕКСЕЙ КОРШУНОВ

Разрабатываем документацию с помощью NPJ: эффективно и удобно!

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

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

Очень часто работа с Open Source-проектом (не важно, его разработка или установка) тесно связана с чтением и написанием документации. Все мы знаем, что память человека обладает избирательностью и имеет свойство убирать «на дальнюю полку» неиспользуемые в данный момент знания. Количество же таких знаний напрямую зависит от вашего опыта работы и размера серверного парка вашей компании.

По своему опыту могу сказать, что пара десятков грамотно написанных (собственноручно) документов по настройке «типовых» решений – сильно облегчают жизнь и навсегда избавляют от мучительных воспоминаний. Больше нет раздумий о том, что же я на этот раз забыл куда прописать и какой нюанс, встретившийся когда-то, никак не может всплыть из глубин моей памяти. Не стану отрицать, наверное, существуют супер-профессионалы, которые помнят всё и всегда, но мне такие не известны. Гуру, с которыми мне приходилось общаться, нет-нет да и говорили в ответ на вопрос «Что-то такое было... Я точно не помню».

К чему я всё это? А к тому, что привычку писать (хотя бы даже для себя) документацию о настройке сервисов, в которых столкнулись с проблемами, о встретившихся тонкостях и особенностях – можно смело назвать весьма полезной привычкой и крайне необходимой практикой. Это логическое продолжение привычки многих людей – записывать в КПК, документы и другие менее удобные для поиска информации источники.

Что такое NPJ

Для разработки документации из наиболее удобных инструментов можно выделить «НетПроектЖурнал» или просто NPJ. Он построен на принципах работы любого Open Source-проекта. Люди объединяются в сообщества (рабочие группы) и работают над какой-либо документацией. Для примера ведения проекта могу привести весьма простой, но от того не менее удобный биллинг «cake» (http://npj.ru/cake). В данном случае сайт проекта является и его главной страницей, и местом разработки документации, и местом поддержки проекта, так как NPJ – гибкий инструмент и фактически может выступать в любом качестве. Для примера ресурса, основная цель которого разработка и сбор документации, могу привести npj.akeeper.ru. Учитывая весьма продвинутые средства поиска по узлу NPJ – это крайне удобный инструмент.

Суть удобств:

• Установка и настройка, как правило, занимает 5-10 минут.
• Гибкость архитектуры позволяет создавать на вашем узле практически всё что угодно – от банального блога (есть ресурс, где NPJ используется для ведения личных дневников livejournal) до серьёзного ресурса по разработке, представлению и ведению проекта.
• Сквозная авторизация на узлах других систем (о ней чуть ниже) позволяет вам принимать участие в работе на любых узлах, подключённых к общей сети NPJ-узлов.
• На одном узле может быть создано сколь угодно много рабочих групп, каждой из которых допустимо заниматься своим независимым проектом.
• Рабочие группы могут быть публичные, премодерируемые, скрытые.
• Любая страница внутри узла может выступать в любом качестве – от обычного документа, до формы форума (об этом тоже чуть позже).
• Помимо участия в рабочих группах пользователь узла всегда имеет собственный личный журнал и возможность создания своих документов.
• Гибкость настройки системы прав позволяет определить, кто, к чему, какой будет иметь доступ. (Это касается как документов и записей рабочей группы, так и документов с записями любого пользователя. Только вы решаете, с каким доступом создаете запись или документ.)
• Несколько способов представления индекса и разбиения по категориям всей документации рабочей группы.
• Легкость поиска по всему узлу.
• В узле, при условии соответствующей настройки доступа, комментировать можно всё, а получать комментарии и отвечать на них можно прямо из вашего почтового клиента. (Больше никаких идиотских писем: «Появился новый комментарий, на который вы подписаны. Пройдите по ссылке, чтобы его увидеть» – забудьте! Жить стало значительно проще и удобнее.)
• При разработке документации ведётся история её изменения, которую всегда можно просмотреть и точно узнать, какие правки и добавления были произведены. Более того, всегда можно вернуться к одной из сохранённых версий документа.
• Документ можно анонсировать по рабочим группам, сообщив таким образом о его существовании. Есть возможность создать дайджест.
• Благодаря Wiki-разметке, писать документы не просто, а очень просто. И крайне приятно.
• Интерфейс для каждой группы, пользователя настраивается индивидуально.
• Возможность прямо с центральной страницы увидеть все документы, изменения в документах всех пользователей, ленту всех пользователей, ленту всех анонсов, список изменений в дайджестах и так далее.
• Поддержка RSS.
• Есть багтрекер.

Выше я упоминал сквозную авторизацию на разных узлах. Дело в том, что каждый узел «НетПроектЖурнала» имеет возможность войти в объединённую общую сеть. Это производится нажатием пары ссылок в настройках. Механизм работы этой системы довольно прост – при заходе на любую гостевую NPJ система находит куки-файл от родного (для вас) хоста и запрашивает у него вашу авторизацию. Если ваш хост авторизацию подтверждает, то на гостевом узле вы будете представлены под именем yournick@yourhost, и вся ваша деятельность перестаёт быть анонимной. Почему это важно?

Благодаря авторизованной таким образом деятельности вы можете подписаться на уведомления с разных узлов. Это одна из самых полезных функций NPJ. Можно получать уведомления о:

• Создании новых документов. В том числе, получать в письме весь новый документ, со всей разметкой.
• Изменениях в существующих документах.
• Анонсах на узлах (о создании новых групп, сообществ, разработок).
• Новых комментариях к записям, в том числе отвечать на эти комментарии прямо из вашей любимой почтовой программы.
• Прочие уведомления.

Особого внимания заслуживает то, что любая страница журнала может выступать в совершенно разных качествах. Для пояснения необходимо немного рассказать об архитектуре этой системы. Суть архитектуры «НетПроектЖурнал» можно было бы охарактеризовать как «вот вам пластилин, что на ум пришло, то и лепите». Это значит, что каждая страница доступна для редактирования и может как содержать информацию в самой себе, так и являться (например) оглавлением для раздела. Вы можете создать ссылку в теле страницы на объект, который не существует. А сразу после сохранения созданной страницы можно перейти на эту ссылку и тут же создать документ, который будет по ней располагаться. И только вам решать, будет это документом или очередным оглавлением, каталогом, индексом, гостевой книгой или чем-то ещё.

Потенциальный «минус», который довольно скоро бросается в глаза, – отсутствие возможности загрузки на сервер узла файлов через веб-интерфейс. Другими словами, если вы хотите разместить в документе или где-то ещё ссылку на файл, то для размещения этого файла на сервере вам придётся воспользоваться помощью других сервисов.

Ещё одна деталь, на которую хотелось бы обратить ваше внимание.NPJ написан c применением концепций ООП, а следовательно, добавление функциональности не составляет особого труда. Например, в мою NPJ-систему были внесены необходимые изменения, которые позволили использовать одну общую базу пользователей как для этой системы, так и для phpbb2 форума. Это оказалось весьма удобно, а реализация не заняла и двух дней.

Как NPJ выглядит и работает

Для установки NPJ-узла не требуется неординарных усилий. Всё происходит гладко, и система встаёт, что называется, из коробки. На сайте проекта (http://www.npj.ru) содержится детальная информация по установке, и там же можно всегда скачать последнюю версию системы. Начать работу лучше всего с изучения страницы http://npj.ru/npjdev/release. Для работы NPJ необходимы: Apache (возможно, он так же будет работать и с другими веб-серверами), MySQL, а также PHP. На сайте проекта нет информации о минимально необходимой конфигурации компьютера для установки. Однако я устанавливал NPJ на Linux-машины следующей конфигурации (PIII, 256 Мб RAM, 10 Гб HDD) и никаких проблем в работе не замечал.

Я не буду описывать процесс конфигурирования нового узла, так как уже выше было сказано – исчерпывающая информация находится на сайте разработчиков (который представляет из себя такой же NPJ-узел). Единственное, обращу ваше внимание на две настройки. Если вы хотите получать уведомления на почту, то придётся создать почтовый аккаунт для NPJ и обеспечить к нему pop3-доступ. Настройки для этого прописываются в файле config_tunes.php. И если вы хотите принимать участие в работе на других узлах с теми приятными мелочами, что были описаны выше, включите интеграцию вашего узла в общую сеть. Это делается двумя кликами на странице администрирования – http://npj.example.ru/manage/nns.

После установки в вашем распоряжении будет одна группа, по умолчанию называющаяся node@имяузла, а также личная область, доступная всем пользователям (см. рис. 1).

Рисунок 1. Пример внешнего вида личного пространства

Вы можете выбрать несколько вариантов оформления узла для вас, а также умолчания для тех пользователей, которые не сделали собственных предустановок. Первое делается в настройках вашего профиля, а второе, соответственно, в настройках узла. По умолчанию выставлен стиль «simplifica», но многие предпочитают более аскетичный стиль «academic». Мне, правда, не нравится ни тот, ни другой, так как их функциональность для меня не подходит. Я использую «minikui», который вы можете видеть на рис. 1. Его основное преимущество – удобство в быстром доступе к множеству функций и свойств страницы. Например, к своему стыду, я так и не понял, как в стиле «academic» добиться быстрого и удобного (а главное постоянного, вне зависимости от просматриваемой страницы) доступа к поиску.

Есть и другие причины заглянуть в пользовательские настройки. Например, там есть выбор между использованием вики/вака разметки и более наглядного редактора в стиле MS Word.

В личной области вы можете вести свой дневник (как тот же livejournal) и, например, таким образом протоколировать для себя разработки на узле. Там же у вас есть возможность создавать собственные документы, не привязанные ни к какой рабочей группе. Строго говоря, рабочие группы вообще не обязательный атрибут, если узел создавался не с целью обеспечения какого-либо проекта, которым занимаются много людей. Мне известно немало случаев, когда NPJ ставили на собственной локальной машине и использовали исключительно в личных целях.

Как только вы увидите всё это богатство, возникнет вопрос – как же всем этим пользоваться. К сожалению или к счастью, NPJ имеет достаточно высокий «уровень вхождения», поэтому на первых порах у пользователей возникает множество вопросов о способах взаимодействия с узлом. Здесь на помощь приходит выражение, которое уже прозвучало выше, – каждая страница узла – это «пластилин», из которого вы можете «лепить» что угодно. Для того, чтобы понять, о чем я говорю, просто кликните дважды на любой странице узла. Например, на центральной. И если вы обладаете администраторскими правами – получите окно для редактирования страницы (см. рис. 2).

Рисунок 2. Начинать творить можно отсюда

Начиная с этого момента вы можете как угодно до неузнаваемости изменить главную страницу вашего узла. Воспользуйтесь ссылкой на описание различных тегов и разметки – http://www.npj.ru/node/chastyevoprosy/zapisizhurnala/wikisintaksis. Есть неписаные стандарты оформления главной страницы. Однако следовать им вовсе не обязательно. Вы можете посмотреть, как могут выглядеть заглавные страницы просто попутешествовав по разным узлам.

Рисунок 3. Типичное оформление главной страницы узла

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

Рабочие группы на узлах NPJ – это фактически разграничение прав между пользователями узла. Они существуют для определения политики выдачи (отображения) информации, с которой работают члены группы, а также для определения прав доступа каждого члена. Группы могут быть публичными, премодерируемыми, а также, как уже упоминалось, скрытыми.

Рисунок 4. Рассматриваем группы более внимательно

Члены групп могут обладать разными правами, от читательских до менеджерских (администраторских). Разумеется, в пределах своих групп. Если пользователь является менеджером пусть даже основной рабочей группы node@имяузла – это не означает, что он становится администратором узла.

Если вы создали рабочую группу (или же решили использовать уже существующую), то можете сразу приступить к оформлению и наполнению её материалами. Для этого достаточно зайти на страницу группы, которая, как правило, выглядит http://имяузла/имярабгруппы и точно так же, как на центральной странице, кликнуть на ней дважды. Откроется уже знакомое окно редактирования.

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

Для пробы описанных выше возможностей давайте создадим на странице новой рабочей группы ссылку на два объекта. Допустим, что первая ссылка будет документом, а вторая – оглавлением (см. рис. 5).

Рисунок 5. Начинаем мять «пластилин»

После сохранения мы увидим подчёркнутые пунктиром наши ссылки и знак вопроса в конце. При клике на этот знак вопроса нам будет предложено создать не существующий пока объект.

Теперь заполним первую страницу текстом, а на второй сделаем оглавление (см. рис. 6).

Рисунок 6. Две инкарнации одинаковых страниц

Как вы видите, от того, что страницы нами предназначались для разных целей, – суть их не изменилась. Мы можем в первый документ добавить оглавление какого-нибудь нового раздела. А можем, наоборот, на второй созданной странице написать текст и разместить (к примеру) картинку.

В любой момент вы можете просмотреть код практически любой страницы (причем необязательно только вашего узла). Для этого достаточно набрать http://npj.example.ru/page/source, и вы получите указанную страницу в wiki-разметке.

Надеюсь, теперь вы поняли, что каждая страница NPJ-узла – это шаблон, в котором может находиться всё, что вам заблагорассудится. Фактически это можно представить как кучу html-файлов, которые между собой увязаны так, как вы сами посчитали необходимым. От обычных html-текстов их отличает только удобство использования, удобство редактирования и прочие «полезности», что уже были озвучены выше.

Использование NPJ в работе

Какую конкретно документацию вести в NPJ, решать вам. От себя я могу поделиться той схемой, благодаря которой у меня навсегда исчезла проблема ответа на вопрос (начальству или самому себе), что где находится и как оно работает. Эта схема использовалась в компании «Город-Инфо» (см. рис. 7).

Рисунок 7. Структура рабочей группы «Город-Инфо»

Как видно из рисунка, фактически все области работы службы системных администраторов компании здесь освещены. Разумеется, часть информации не отображена на схеме и включена в пункты «прочее», но и того, что отображено, более чем достаточно для понимания. Стрелками отображены ссылки между разделами. Множество перекрёстных ссылок находится и внутри документов, но отобразить это на схеме не представляется возможным.

Там же системными администраторами компании велась разработка документации, которая впоследствии предоставлялась клиентам и заказчикам. NPJ позволяла не только вместе выполнять такие работы, но и отслеживать изменения в документе. А также предоставляла площадь для дебатов по поводу внесения тех или иных изменений. Впоследствии там же должна была начаться разработка целого пакета документации, так как именно это средство было признано наиболее подходящим для проведения такой работы (разработка с участием географически сильно удалённых пользователей), но к тому времени я покинул компанию.

Не буду рассказывать, как нам помогала в работе документация, составленная в NPJ весьма помагала в работе. Мы забыли, что такое «гадать» или в чем-то сомневаться. Просто открываешь браузер, и вся детальная информация перед глазами.

Выводы

Способов применения в работе узла NPJ ровно столько, сколько вы сможете придумать. Может быть, вы предпочтёте записывать в собственный журнал интересные находки «на будущее», а в документах сохранять, к примеру, особо удачные конфигурационные файлы или же их описание. Может быть, вы создадите отдельную рабочую группу, где будете вести всю документацию по своей сети. А может, вы посвятите свой узел поддержке какого-либо проекта, разработкой которого в данный момент занимаетесь или только планируете заняться.

Многие тонкости работы NPJ остались за рамками статьи. Причин для этого несколько. Во-первых, несмотря на то, что я давно пользуюсь этой системой, для меня ещё не все тонкости раскрыты. Во-вторых, многое из оставленного за рамками статьи относится к редко используемому, и далеко не всем будет интересно. Например, работа с «Сообществами», внутри которых создавать документы нельзя. Эта такая дискуссионная форма, но применения ей я не нашёл, поэтому в своём рассказе пропустил. А самую сложную проблему в использовании NPJ, понимание, как это работает, хочется надеяться, я помог вам разрешить.

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