Blogerator.org

× Версия для печати

Я долго думал над тем, в каком формате хранить пользовательскую документацию к разрабатываемым мной программным продуктам. Главное мое требование заключается в следующем: 1) документация должна быть всегда доступна в режиме онлайн и 2) должна быть возможность получения фидбэка от пользователей.

В поисках оптимального решения мне пришлось переделывать сайты с документацией несколько раз.

Сначала я сделал так: взял Wordpress, немного «допилил» под собственные нужды, развернул на сервере — и получился сайт с документацией.

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

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

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

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

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

Я пишу текст в Sublime, использую простейшее форматирование (markdown), копирую файл в локальный репозиторий блога, добавляю YAML-заголовок с названием, тэгами и т.п., затем отправляю на ГитХаб и разворачиваю на хостинге при помощи инструмента Fabric.

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

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

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

Самое главное преимущество облачного хранилища «Селектел» — это, конечно же, цена. Мой сайт «весит» в общей сложности три с небольшим мегабайта. Оплата в облачном хранилище взимается как за объем хранимой информации, так и за исходящий трафик (т.е. за объем информации, скачиваемый посетителями сайта).Его хостинг обходится мне в месяц в три рубля с копейками — и это вместе с исходящим трафиком. На текущий момент я новым хостингом более чем доволен.

Резюмируя сказанное, перечислю основные преимущества, которые я получил благодаря переходу на статику:

• решена проблема со вставкой программного кода;
• статический HTML: все работает быстро, хостить можно где угодно;
• редактировать страницы сайта можно даже на ГитХабе;
• хостинг обходится в сущие копейки;

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

Автор: Ростислав Ежов